@kya-os/mcp-i 1.4.0 → 1.5.1

package/dist/runtime/delegation-verifier-agentshield.js

@@ -0,0 +1,301 @@
+"use strict";
+/**
+ * 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)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentShieldAPIDelegationVerifier = void 0;
+const delegation_1 = require("@kya-os/contracts/delegation");
+const delegation_verifier_1 = require("./delegation-verifier");
+/**
+ * Simple in-memory cache (same as KV verifier)
+ */
+class DelegationCache {
+    cache = new Map();
+    maxSize;
+    constructor(maxSize = 1000) {
+        this.maxSize = maxSize;
+    }
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return null;
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry.data;
+    }
+    set(key, data, ttlMs) {
+        if (this.cache.size >= this.maxSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey)
+                this.cache.delete(firstKey);
+        }
+        this.cache.set(key, {
+            data,
+            expiresAt: Date.now() + ttlMs,
+        });
+    }
+    delete(key) {
+        this.cache.delete(key);
+    }
+    clear() {
+        this.cache.clear();
+    }
+}
+/**
+ * AgentShield API Delegation Verifier
+ *
+ * Managed mode: Queries delegations from AgentShield dashboard API
+ */
+class AgentShieldAPIDelegationVerifier {
+    apiUrl;
+    apiKey;
+    cache;
+    cacheTtl;
+    debug;
+    constructor(config) {
+        if (!config.agentshield?.apiUrl || !config.agentshield?.apiKey) {
+            throw new Error('AgentShieldAPIDelegationVerifier requires agentshield.apiUrl and agentshield.apiKey in config');
+        }
+        this.apiUrl = config.agentshield.apiUrl.replace(/\/$/, ''); // Remove trailing slash
+        this.apiKey = config.agentshield.apiKey;
+        this.cache = new DelegationCache();
+        this.cacheTtl = config.cacheTtl || 60_000; // Default 1 minute
+        this.debug = config.debug || false;
+    }
+    /**
+     * Verify agent delegation via API
+     */
+    async verify(agentDid, scopes, options) {
+        const startTime = Date.now();
+        // Build cache key
+        const scopesKey = this.buildScopesKey(scopes);
+        const cacheKey = `verify:${agentDid}:${scopesKey}`;
+        // Fast path: Check cache
+        if (!options?.skipCache) {
+            const cached = this.cache.get(cacheKey);
+            if (cached) {
+                if (this.debug) {
+                    console.log(`[AgentShield] Cache HIT for ${agentDid} (${Date.now() - startTime}ms)`);
+                }
+                return { ...cached, cached: true };
+            }
+        }
+        // Slow path: API call
+        if (this.debug) {
+            console.log(`[AgentShield] Cache MISS for ${agentDid}, calling API...`);
+        }
+        try {
+            const response = await fetch(`${this.apiUrl}/api/v1/delegations/verify`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-API-Key': this.apiKey,
+                },
+                body: JSON.stringify({
+                    agentDid,
+                    scopes,
+                }),
+            });
+            if (!response.ok) {
+                // Handle API errors
+                if (response.status === 404) {
+                    const result = {
+                        valid: false,
+                        reason: 'No delegation found',
+                        cached: false,
+                    };
+                    this.cache.set(cacheKey, result, this.cacheTtl / 2);
+                    return result;
+                }
+                if (response.status === 401 || response.status === 403) {
+                    throw new Error(`AgentShield API authentication failed: ${response.status}`);
+                }
+                throw new Error(`AgentShield API error: ${response.status} ${response.statusText}`);
+            }
+            const data = await response.json();
+            // Validate response
+            if (data.delegation) {
+                const parsed = delegation_1.DelegationRecordSchema.safeParse(data.delegation);
+                if (!parsed.success) {
+                    console.error('[AgentShield] Invalid delegation in API response:', parsed.error);
+                    data.valid = false;
+                    data.reason = 'Invalid delegation format';
+                }
+                else {
+                    // Re-validate locally (trust but verify)
+                    const validation = (0, delegation_verifier_1.validateDelegation)(parsed.data);
+                    if (!validation.valid) {
+                        data.valid = false;
+                        data.reason = validation.reason;
+                    }
+                }
+            }
+            const result = {
+                valid: data.valid,
+                delegation: data.delegation,
+                reason: data.reason,
+                cached: false,
+            };
+            // Cache result
+            const ttl = data.valid ? this.cacheTtl : this.cacheTtl / 2;
+            this.cache.set(cacheKey, result, ttl);
+            if (this.debug) {
+                console.log(`[AgentShield] Delegation ${data.valid ? 'verified' : 'rejected'} (${Date.now() - startTime}ms)`);
+            }
+            return result;
+        }
+        catch (error) {
+            console.error('[AgentShield] API call failed:', error);
+            // Return negative result on error (don't cache failures)
+            return {
+                valid: false,
+                reason: `API error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                cached: false,
+            };
+        }
+    }
+    /**
+     * Get delegation by ID via API
+     */
+    async get(delegationId) {
+        const cacheKey = `delegation:${delegationId}`;
+        // Check cache
+        const cached = this.cache.get(cacheKey);
+        if (cached)
+            return cached;
+        try {
+            const response = await fetch(`${this.apiUrl}/api/v1/delegations/${delegationId}`, {
+                method: 'GET',
+                headers: {
+                    'X-API-Key': this.apiKey,
+                },
+            });
+            if (!response.ok) {
+                if (response.status === 404)
+                    return null;
+                throw new Error(`AgentShield API error: ${response.status}`);
+            }
+            const data = await response.json();
+            const parsed = delegation_1.DelegationRecordSchema.safeParse(data);
+            if (!parsed.success) {
+                console.error('[AgentShield] Invalid delegation in API response:', parsed.error);
+                return null;
+            }
+            const delegation = parsed.data;
+            // Cache it
+            this.cache.set(cacheKey, delegation, this.cacheTtl);
+            return delegation;
+        }
+        catch (error) {
+            console.error('[AgentShield] Failed to get delegation:', error);
+            return null;
+        }
+    }
+    /**
+     * Store delegation (admin operation via API)
+     *
+     * Note: This is typically done via AgentShield dashboard UI,
+     * not by the bouncer directly. Included for completeness.
+     */
+    async put(delegation) {
+        // Validate first
+        const parsed = delegation_1.DelegationRecordSchema.safeParse(delegation);
+        if (!parsed.success) {
+            throw new Error(`Invalid delegation record: ${parsed.error.message}`);
+        }
+        try {
+            const response = await fetch(`${this.apiUrl}/api/v1/delegations`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-API-Key': this.apiKey,
+                },
+                body: JSON.stringify(delegation),
+            });
+            if (!response.ok) {
+                throw new Error(`AgentShield API error: ${response.status} ${response.statusText}`);
+            }
+            // Invalidate cache
+            const delegationScopes = (0, delegation_verifier_1.extractScopes)(delegation);
+            const scopesKey = this.buildScopesKey(delegationScopes);
+            this.cache.delete(`delegation:${delegation.id}`);
+            this.cache.delete(`verify:${delegation.subjectDid}:${scopesKey}`);
+            if (this.debug) {
+                console.log(`[AgentShield] Stored delegation ${delegation.id}`);
+            }
+        }
+        catch (error) {
+            console.error('[AgentShield] Failed to store delegation:', error);
+            throw error;
+        }
+    }
+    /**
+     * Revoke delegation via API
+     */
+    async revoke(delegationId, reason) {
+        try {
+            const response = await fetch(`${this.apiUrl}/api/v1/delegations/${delegationId}/revoke`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-API-Key': this.apiKey,
+                },
+                body: JSON.stringify({ reason }),
+            });
+            if (!response.ok) {
+                throw new Error(`AgentShield API error: ${response.status} ${response.statusText}`);
+            }
+            // Invalidate cache
+            this.cache.delete(`delegation:${delegationId}`);
+            if (this.debug) {
+                console.log(`[AgentShield] Revoked delegation ${delegationId}`);
+            }
+        }
+        catch (error) {
+            console.error('[AgentShield] Failed to revoke delegation:', error);
+            throw error;
+        }
+    }
+    /**
+     * Close connections (cleanup)
+     */
+    async close() {
+        this.cache.clear();
+    }
+    /**
+     * Build deterministic scopes key for caching
+     */
+    buildScopesKey(scopes) {
+        const sorted = [...scopes].sort();
+        const str = sorted.join(',');
+        let hash = 0;
+        for (let i = 0; i < str.length; i++) {
+            const char = str.charCodeAt(i);
+            hash = (hash << 5) - hash + char;
+            hash = hash & hash;
+        }
+        return Math.abs(hash).toString(36);
+    }
+}
+exports.AgentShieldAPIDelegationVerifier = AgentShieldAPIDelegationVerifier;

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

@@ -0,0 +1,51 @@
+/**
+ * Cloudflare KV Delegation Verifier
+ *
+ * Stores delegations in Cloudflare Workers KV for high-performance,
+ * edge-cached delegation verification.
+ *
+ * Performance:
+ * - Fast path (cached): < 5ms
+ * - Slow path (KV read): < 50ms
+ * - Cache TTL: 1 minute (configurable)
+ *
+ * Key Structure:
+ * - `delegation:{delegationId}` - Full delegation record
+ * - `agent:{agentDid}:scopes:{hash}` - Delegation lookup by agent+scopes
+ *
+ * Related: PHASE_1_XMCP_I_SERVER.md Ticket 1.2
+ */
+import { DelegationRecord } from '@kya-os/contracts/delegation';
+import { DelegationVerifier, DelegationVerifierConfig, VerifyDelegationResult, VerifyDelegationOptions } from './delegation-verifier';
+/**
+ * Cloudflare KV Delegation Verifier
+ *
+ * Self-hosted mode: Stores delegations in local Cloudflare KV namespace
+ */
+export declare class CloudflareKVDelegationVerifier implements DelegationVerifier {
+    private kv;
+    private cache;
+    private cacheTtl;
+    private debug;
+    constructor(config: DelegationVerifierConfig);
+    /**
+     * Verify agent delegation
+     */
+    verify(agentDid: string, scopes: string[], options?: VerifyDelegationOptions): Promise<VerifyDelegationResult>;
+    /**
+     * Get delegation by ID
+     */
+    get(delegationId: string): Promise<DelegationRecord | null>;
+    /**
+     * Store delegation record
+     */
+    put(delegation: DelegationRecord): Promise<void>;
+    /**
+     * Revoke delegation
+     */
+    revoke(delegationId: string, reason?: string): Promise<void>;
+    /**
+     * Build deterministic scopes key for caching/lookup
+     */
+    private buildScopesKey;
+}

package/dist/runtime/delegation-verifier-kv.js

@@ -0,0 +1,280 @@
+"use strict";
+/**
+ * Cloudflare KV Delegation Verifier
+ *
+ * Stores delegations in Cloudflare Workers KV for high-performance,
+ * edge-cached delegation verification.
+ *
+ * Performance:
+ * - Fast path (cached): < 5ms
+ * - Slow path (KV read): < 50ms
+ * - Cache TTL: 1 minute (configurable)
+ *
+ * Key Structure:
+ * - `delegation:{delegationId}` - Full delegation record
+ * - `agent:{agentDid}:scopes:{hash}` - Delegation lookup by agent+scopes
+ *
+ * Related: PHASE_1_XMCP_I_SERVER.md Ticket 1.2
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloudflareKVDelegationVerifier = void 0;
+const delegation_1 = require("@kya-os/contracts/delegation");
+const delegation_verifier_1 = require("./delegation-verifier");
+/**
+ * Simple in-memory LRU cache for delegation lookups
+ */
+class DelegationCache {
+    cache = new Map();
+    maxSize;
+    constructor(maxSize = 1000) {
+        this.maxSize = maxSize;
+    }
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return null;
+        // Check expiration
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry.data;
+    }
+    set(key, data, ttlMs) {
+        // Simple LRU: if cache is full, delete oldest entry
+        if (this.cache.size >= this.maxSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey)
+                this.cache.delete(firstKey);
+        }
+        this.cache.set(key, {
+            data,
+            expiresAt: Date.now() + ttlMs,
+        });
+    }
+    delete(key) {
+        this.cache.delete(key);
+    }
+    clear() {
+        this.cache.clear();
+    }
+}
+/**
+ * Cloudflare KV Delegation Verifier
+ *
+ * Self-hosted mode: Stores delegations in local Cloudflare KV namespace
+ */
+class CloudflareKVDelegationVerifier {
+    kv; // KVNamespace from @cloudflare/workers-types
+    cache;
+    cacheTtl;
+    debug;
+    constructor(config) {
+        if (!config.kvNamespace) {
+            throw new Error('CloudflareKVDelegationVerifier requires kvNamespace in config');
+        }
+        this.kv = config.kvNamespace;
+        this.cache = new DelegationCache();
+        this.cacheTtl = config.cacheTtl || 60_000; // Default 1 minute
+        this.debug = config.debug || false;
+    }
+    /**
+     * Verify agent delegation
+     */
+    async verify(agentDid, scopes, options) {
+        const startTime = Date.now();
+        // Build cache key from agent DID + sorted scopes
+        const scopesKey = this.buildScopesKey(scopes);
+        const cacheKey = `verify:${agentDid}:${scopesKey}`;
+        // Fast path: Check cache first (unless skipCache is true)
+        if (!options?.skipCache) {
+            const cached = this.cache.get(cacheKey);
+            if (cached) {
+                if (this.debug) {
+                    console.log(`[KV] Cache HIT for ${agentDid} (${Date.now() - startTime}ms)`);
+                }
+                return { ...cached, cached: true };
+            }
+        }
+        // Slow path: Lookup in KV
+        if (this.debug) {
+            console.log(`[KV] Cache MISS for ${agentDid}, querying KV...`);
+        }
+        // List all delegations for this agent (to support subset scope matching)
+        const listResult = await this.kv.list({ prefix: `agent:${agentDid}:scopes:` });
+        if (!listResult.keys || listResult.keys.length === 0) {
+            const result = {
+                valid: false,
+                reason: 'No delegation found for agent',
+                cached: false,
+            };
+            // Cache negative result (shorter TTL)
+            this.cache.set(cacheKey, result, this.cacheTtl / 2);
+            if (this.debug) {
+                console.log(`[KV] No delegation found (${Date.now() - startTime}ms)`);
+            }
+            return result;
+        }
+        // Try each delegation to find one that matches the requested scopes
+        let matchingDelegation = null;
+        for (const key of listResult.keys) {
+            const delegationId = await this.kv.get(key.name, 'text');
+            if (!delegationId)
+                continue;
+            const delegation = await this.get(delegationId);
+            if (!delegation)
+                continue;
+            // Check if this delegation has the required scopes
+            const delegationScopes = (0, delegation_verifier_1.extractScopes)(delegation);
+            const scopesMatch = (0, delegation_verifier_1.checkScopes)(delegationScopes, scopes);
+            if (scopesMatch) {
+                // Found a matching delegation!
+                matchingDelegation = delegation;
+                break;
+            }
+        }
+        if (!matchingDelegation) {
+            const result = {
+                valid: false,
+                reason: 'No delegation found with required scopes',
+                cached: false,
+            };
+            this.cache.set(cacheKey, result, this.cacheTtl / 2);
+            if (this.debug) {
+                console.log(`[KV] No matching delegation found (${Date.now() - startTime}ms)`);
+            }
+            return result;
+        }
+        const delegation = matchingDelegation;
+        // Validate delegation
+        const validation = (0, delegation_verifier_1.validateDelegation)(delegation);
+        if (!validation.valid) {
+            const result = {
+                valid: false,
+                delegation,
+                reason: validation.reason,
+                cached: false,
+            };
+            this.cache.set(cacheKey, result, this.cacheTtl / 2);
+            return result;
+        }
+        // Check scopes
+        const delegationScopes = (0, delegation_verifier_1.extractScopes)(delegation);
+        const scopesMatch = (0, delegation_verifier_1.checkScopes)(delegationScopes, scopes);
+        if (!scopesMatch) {
+            const result = {
+                valid: false,
+                delegation,
+                reason: 'Insufficient scopes',
+                cached: false,
+            };
+            this.cache.set(cacheKey, result, this.cacheTtl / 2);
+            return result;
+        }
+        // Success!
+        const result = {
+            valid: true,
+            delegation,
+            cached: false,
+        };
+        // Cache positive result
+        this.cache.set(cacheKey, result, this.cacheTtl);
+        if (this.debug) {
+            console.log(`[KV] Delegation verified (${Date.now() - startTime}ms)`);
+        }
+        return result;
+    }
+    /**
+     * Get delegation by ID
+     */
+    async get(delegationId) {
+        const cacheKey = `delegation:${delegationId}`;
+        // Check cache
+        const cached = this.cache.get(cacheKey);
+        if (cached)
+            return cached;
+        // Fetch from KV
+        const kvKey = `delegation:${delegationId}`;
+        const raw = await this.kv.get(kvKey, 'text');
+        if (!raw)
+            return null;
+        try {
+            const data = JSON.parse(raw);
+            const parsed = delegation_1.DelegationRecordSchema.safeParse(data);
+            if (!parsed.success) {
+                console.error('[KV] Invalid delegation record:', parsed.error);
+                return null;
+            }
+            const delegation = parsed.data;
+            // Cache it
+            this.cache.set(cacheKey, delegation, this.cacheTtl);
+            return delegation;
+        }
+        catch (error) {
+            console.error('[KV] Failed to parse delegation:', error);
+            return null;
+        }
+    }
+    /**
+     * Store delegation record
+     */
+    async put(delegation) {
+        // Validate first
+        const parsed = delegation_1.DelegationRecordSchema.safeParse(delegation);
+        if (!parsed.success) {
+            throw new Error(`Invalid delegation record: ${parsed.error.message}`);
+        }
+        const validated = parsed.data;
+        // Store full delegation record
+        const kvKey = `delegation:${validated.id}`;
+        await this.kv.put(kvKey, JSON.stringify(validated));
+        // Create lookup key for agent + scopes
+        const delegationScopes = (0, delegation_verifier_1.extractScopes)(validated);
+        const scopesKey = this.buildScopesKey(delegationScopes);
+        const lookupKey = `agent:${validated.subjectDid}:scopes:${scopesKey}`;
+        await this.kv.put(lookupKey, validated.id);
+        // Invalidate cache
+        this.cache.delete(`delegation:${validated.id}`);
+        this.cache.delete(`verify:${validated.subjectDid}:${scopesKey}`);
+        if (this.debug) {
+            console.log(`[KV] Stored delegation ${validated.id}`);
+        }
+    }
+    /**
+     * Revoke delegation
+     */
+    async revoke(delegationId, reason) {
+        const delegation = await this.get(delegationId);
+        if (!delegation) {
+            throw new Error(`Delegation not found: ${delegationId}`);
+        }
+        // Update status
+        delegation.status = 'revoked';
+        delegation.revokedAt = Date.now();
+        if (reason) {
+            delegation.revokedReason = reason;
+        }
+        // Store updated record
+        await this.put(delegation);
+        if (this.debug) {
+            console.log(`[KV] Revoked delegation ${delegationId}`);
+        }
+    }
+    /**
+     * Build deterministic scopes key for caching/lookup
+     */
+    buildScopesKey(scopes) {
+        // Sort scopes for deterministic key
+        const sorted = [...scopes].sort();
+        // Simple hash (for production, consider crypto.subtle.digest)
+        const str = sorted.join(',');
+        let hash = 0;
+        for (let i = 0; i < str.length; i++) {
+            const char = str.charCodeAt(i);
+            hash = (hash << 5) - hash + char;
+            hash = hash & hash; // Convert to 32-bit integer
+        }
+        return Math.abs(hash).toString(36);
+    }
+}
+exports.CloudflareKVDelegationVerifier = CloudflareKVDelegationVerifier;

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

@@ -0,0 +1,50 @@
+/**
+ * Memory Delegation Verifier
+ *
+ * Simple in-memory delegation storage for testing and development.
+ * NOT suitable for production - delegations lost on restart.
+ *
+ * Use for:
+ * - Unit tests
+ * - Local development
+ * - Integration tests
+ *
+ * Related: PHASE_1_XMCP_I_SERVER.md Testing section
+ */
+import { DelegationRecord } from '@kya-os/contracts/delegation';
+import { DelegationVerifier, DelegationVerifierConfig, VerifyDelegationResult, VerifyDelegationOptions } from './delegation-verifier';
+/**
+ * Memory Delegation Verifier
+ *
+ * Simple in-memory storage (for testing only)
+ */
+export declare class MemoryDelegationVerifier implements DelegationVerifier {
+    private delegations;
+    private agentIndex;
+    private debug;
+    constructor(config: DelegationVerifierConfig);
+    /**
+     * Verify agent delegation
+     */
+    verify(agentDid: string, scopes: string[], _options?: VerifyDelegationOptions): Promise<VerifyDelegationResult>;
+    /**
+     * Get delegation by ID
+     */
+    get(delegationId: string): Promise<DelegationRecord | null>;
+    /**
+     * Store delegation
+     */
+    put(delegation: DelegationRecord): Promise<void>;
+    /**
+     * Revoke delegation
+     */
+    revoke(delegationId: string, reason?: string): Promise<void>;
+    /**
+     * Clear all delegations (for testing)
+     */
+    clear(): void;
+    /**
+     * Get all delegations (for testing/debugging)
+     */
+    getAll(): DelegationRecord[];
+}