@kya-os/mcp-i 1.7.13 → 1.10.0

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

@@ -1,162 +1,7 @@
 /**
- * Authorization Handshake Module
+ * Authorization Handshake for XMCP-I Runtime — Node.js adapter
  *
- * 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;
-    /** Resume token store (REQUIRED to persist tokens across calls) */
-    resumeTokenStore: ResumeTokenStore;
-    /** 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;
-    /** Credential from AgentShield API (includes authorization method) */
-    credential?: {
-        agent_did: string;
-        user_did: string;
-        scopes: string[];
-        authorization: {
-            type: "oauth" | "oauth2" | "password" | "credential" | "webauthn" | "siwe" | "none";
-            provider?: string;
-            credentialType?: string;
-            rpId?: string;
-            userVerification?: "required" | "preferred" | "discouraged";
-            chainId?: number;
-            domain?: string;
-        };
-        [key: string]: unknown;
-    };
-    /** 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
+ * Re-exports the platform-agnostic auth handshake from @kya-os/mcp-i-core.
+ * All existing public exports are maintained for backward compatibility.
  */
-export declare function hasSensitiveScopes(scopes: string[]): boolean;
+export { verifyOrHints, hasSensitiveScopes, MemoryResumeTokenStore, type AuthHandshakeConfig, type VerifyOrHintsResult, type AgentReputation, type ResumeTokenStore, type DelegationVerifier, type VerifyDelegationResult, } from "@kya-os/mcp-i-core";

package/dist/runtime/auth-handshake.js

@@ -1,254 +1,13 @@
 "use strict";
 /**
- * Authorization Handshake Module
+ * Authorization Handshake for XMCP-I Runtime — Node.js adapter
  *
- * 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)
+ * Re-exports the platform-agnostic auth handshake from @kya-os/mcp-i-core.
+ * All existing public exports are maintained for backward compatibility.
  */
 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.error(`[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.error(`[AuthHandshake] Reputation score: ${reputation.score}`);
-            }
-            // If reputation is too low, require authorization
-            if (reputation.score < config.bouncer.minReputationScore) {
-                if (config.debug) {
-                    console.error(`[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.error(`[AuthHandshake] Delegation valid, authorized (${Date.now() - startTime}ms)`);
-        }
-        return {
-            authorized: true,
-            delegation: delegationResult.delegation,
-            credential: delegationResult.credential, // Include credential for auth method validation
-            reputation,
-            reason: "Valid delegation found",
-        };
-    }
-    // Step 4: No delegation found - return needs_authorization error
-    if (config.debug) {
-        console.error(`[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) {
-    // Use the persistent resume token store from config
-    const resumeToken = await config.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)));
-}
+exports.MemoryResumeTokenStore = exports.hasSensitiveScopes = exports.verifyOrHints = void 0;
+var mcp_i_core_1 = require("@kya-os/mcp-i-core");
+Object.defineProperty(exports, "verifyOrHints", { enumerable: true, get: function () { return mcp_i_core_1.verifyOrHints; } });
+Object.defineProperty(exports, "hasSensitiveScopes", { enumerable: true, get: function () { return mcp_i_core_1.hasSensitiveScopes; } });
+Object.defineProperty(exports, "MemoryResumeTokenStore", { enumerable: true, get: function () { return mcp_i_core_1.MemoryResumeTokenStore; } });