@kya-os/mcp-i 1.4.0 → 1.5.1

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,254 @@
+"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);
+        const errorMessage = `Delegation verification error: ${error instanceof Error ? error.message : 'Unknown error'}`;
+        const authError = await buildNeedsAuthorizationError(agentDid, scopes, config, errorMessage);
+        return {
+            authorized: false,
+            authError,
+            reason: errorMessage,
+        };
+    }
+    // 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;
+}