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

package/dist/auth/handshake.js

@@ -1,250 +0,0 @@
-"use strict";
-/**
- * Authorization Handshake — Platform-agnostic Protocol Reference
- *
- * 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 uses only the global fetch API — no Node-specific imports.
- * It is safe to run on Node.js, Cloudflare Workers, and any fetch-capable runtime.
- *
- * Flow:
- * - If delegation exists + valid → allow (fast path)
- * - If delegation missing → return needs_authorization with hints
- * - If reputation too low (optional) → require authorization
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MemoryResumeTokenStore = void 0;
-exports.verifyOrHints = verifyOrHints;
-exports.hasSensitiveScopes = hasSensitiveScopes;
-const runtime_1 = require("@kya-os/contracts/runtime");
-const logging_1 = require("../logging");
-/**
- * Simple in-memory resume token store (for testing/development).
- * Not suitable for multi-instance deployments.
- */
-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).substring(2, 18)}`;
-        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;
-        if (Date.now() > data.expiresAt) {
-            this.tokens.delete(token);
-            return null;
-        }
-        if (data.fulfilled)
-            return null;
-        return {
-            agentDid: data.agentDid,
-            scopes: data.scopes,
-            createdAt: data.createdAt,
-            expiresAt: data.expiresAt,
-            metadata: data.metadata,
-        };
-    }
-    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.
- */
-async function verifyOrHints(agentDid, scopes, config, _resumeToken) {
-    const startTime = Date.now();
-    if (config.debug) {
-        logging_1.logger.debug(`[AuthHandshake] Verifying ${agentDid} for scopes: ${scopes.join(", ")}`);
-    }
-    let reputation;
-    if (config.kta && config.bouncer.minReputationScore !== undefined) {
-        try {
-            reputation = await fetchAgentReputation(agentDid, config.kta);
-            if (config.debug) {
-                logging_1.logger.debug(`[AuthHandshake] Reputation score: ${reputation.score}`);
-            }
-            if (reputation.score < config.bouncer.minReputationScore) {
-                if (config.debug) {
-                    logging_1.logger.debug(`[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) {
-            logging_1.logger.warn("[AuthHandshake] Failed to check reputation:", error);
-        }
-    }
-    let delegationResult;
-    try {
-        delegationResult = await config.delegationVerifier.verify(agentDid, scopes);
-    }
-    catch (error) {
-        logging_1.logger.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,
-        };
-    }
-    if (delegationResult.valid && delegationResult.delegation) {
-        if (config.debug) {
-            logging_1.logger.debug(`[AuthHandshake] Delegation valid, authorized (${Date.now() - startTime}ms)`);
-        }
-        return {
-            authorized: true,
-            delegation: delegationResult.delegation,
-            credential: delegationResult.credential,
-            reputation,
-            reason: "Valid delegation found",
-        };
-    }
-    if (config.debug) {
-        logging_1.logger.debug(`[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.
- */
-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 isArgusFormat = ktaConfig.apiFormat === "argus";
-    let response;
-    if (isArgusFormat) {
-        response = await fetch(`${apiUrl}/v1/reputation/${encodeURIComponent(agentDid)}`, {
-            method: "POST",
-            headers,
-            body: JSON.stringify({ include_details: false }),
-        });
-    }
-    else {
-        response = await fetch(`${apiUrl}/api/v1/reputation/${encodeURIComponent(agentDid)}`, {
-            method: "GET",
-            headers,
-        });
-    }
-    if (!response.ok) {
-        if (response.status === 404) {
-            return {
-                agentDid,
-                score: 50,
-                totalInteractions: 0,
-                successRate: 0,
-                riskLevel: "unknown",
-                updatedAt: Date.now(),
-            };
-        }
-        throw new Error(`KTA API error: ${response.status} ${response.statusText}`);
-    }
-    const data = (await response.json());
-    const score = data.score ?? 50;
-    const levelRaw = (data.level ??
-        data.riskLevel ??
-        "unknown").toLowerCase();
-    const riskLevel = levelRaw === "low" || levelRaw === "medium" || levelRaw === "high"
-        ? levelRaw
-        : "unknown";
-    return {
-        agentDid: data.agent_did ??
-            data.agentDid ??
-            agentDid,
-        score,
-        totalInteractions: data.totalInteractions ?? 0,
-        successRate: data.successRate ?? 0,
-        riskLevel,
-        updatedAt: data.calculatedAt
-            ? new Date(data.calculatedAt).getTime()
-            : (data.updatedAt ?? Date.now()),
-    };
-}
-/**
- * Build needs_authorization error with hints.
- */
-async function buildNeedsAuthorizationError(agentDid, scopes, config, message) {
-    const resumeToken = await config.resumeTokenStore.create(agentDid, scopes, {
-        requestedAt: Date.now(),
-    });
-    const expiresAt = Date.now() + (config.bouncer.resumeTokenTtl ?? 600_000);
-    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);
-    const authCode = resumeToken.substring(0, 8).toUpperCase();
-    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.
- */
-function hasSensitiveScopes(scopes) {
-    const sensitivePatterns = [
-        "write",
-        "delete",
-        "admin",
-        "payment",
-        "transfer",
-        "execute",
-        "modify",
-    ];
-    return scopes.some((scope) => sensitivePatterns.some((pattern) => scope.toLowerCase().includes(pattern)));
-}
-//# sourceMappingURL=handshake.js.map

package/dist/auth/index.d.ts

@@ -1,6 +0,0 @@
-/**
- * Auth module — platform-agnostic authorization handshake reference implementation.
- */
-export { verifyOrHints, hasSensitiveScopes, MemoryResumeTokenStore, type AuthHandshakeConfig, type VerifyOrHintsResult, type AgentReputation, type ResumeTokenStore, } from "./handshake";
-export type { DelegationVerifier, VerifyDelegationResult } from "./types";
-//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.js

@@ -1,11 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MemoryResumeTokenStore = exports.hasSensitiveScopes = exports.verifyOrHints = void 0;
-/**
- * Auth module — platform-agnostic authorization handshake reference implementation.
- */
-var handshake_1 = require("./handshake");
-Object.defineProperty(exports, "verifyOrHints", { enumerable: true, get: function () { return handshake_1.verifyOrHints; } });
-Object.defineProperty(exports, "hasSensitiveScopes", { enumerable: true, get: function () { return handshake_1.hasSensitiveScopes; } });
-Object.defineProperty(exports, "MemoryResumeTokenStore", { enumerable: true, get: function () { return handshake_1.MemoryResumeTokenStore; } });
-//# sourceMappingURL=index.js.map

package/dist/auth/types.d.ts

@@ -1,46 +0,0 @@
-/**
- * Authorization types for mcp-i-core auth module.
- *
- * These are the minimal interfaces required by the auth handshake.
- * Platform adapters (packages/mcp-i, packages/mcp-i-cloudflare) may extend
- * these types with additional fields.
- */
-import { DelegationRecord } from "@kya-os/contracts/delegation";
-/**
- * Result of a delegation verification check.
- * Structurally compatible with the full VerifyDelegationResult in packages/mcp-i.
- */
-export interface VerifyDelegationResult {
-    /** Whether a valid delegation was found */
-    valid: boolean;
-    /** The delegation record (if found) */
-    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;
-    };
-    /** Reason for invalid result */
-    reason?: string;
-    /** Whether result came from cache */
-    cached?: boolean;
-}
-/**
- * Minimal delegation verifier interface required by verifyOrHints().
- * Concrete implementations live in packages/mcp-i (AgentShieldAPIDelegationVerifier, etc.).
- */
-export interface DelegationVerifier {
-    verify(agentDid: string, scopes: string[]): Promise<VerifyDelegationResult>;
-}
-//# sourceMappingURL=types.d.ts.map

package/dist/auth/types.js

@@ -1,10 +0,0 @@
-"use strict";
-/**
- * Authorization types for mcp-i-core auth module.
- *
- * These are the minimal interfaces required by the auth handshake.
- * Platform adapters (packages/mcp-i, packages/mcp-i-cloudflare) may extend
- * these types with additional fields.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=types.js.map

package/dist/cache/oauth-config-cache.d.ts

@@ -1,69 +0,0 @@
-/**
- * Platform-agnostic cache interface for OAuth provider configurations
- *
- * This interface allows different runtime adapters to provide their own
- * caching implementations (e.g., in-memory for Node.js, KV for Cloudflare)
- *
- * @package @kya-os/mcp-i-core
- */
-import type { OAuthConfig } from "@kya-os/contracts/config";
-/**
- * Cache interface for storing and retrieving OAuth provider configurations
- */
-export interface OAuthConfigCache {
-    /**
-     * Retrieve a cached OAuth configuration
-     * @param key Cache key (typically projectId)
-     * @returns Cached config or null if not found/expired
-     */
-    get(key: string): Promise<OAuthConfig | null>;
-    /**
-     * Store an OAuth configuration in cache
-     * @param key Cache key (typically projectId)
-     * @param value OAuth configuration to cache
-     * @param ttl Time-to-live in milliseconds
-     */
-    set(key: string, value: OAuthConfig, ttl: number): Promise<void>;
-    /**
-     * Clear all cached entries
-     */
-    clear(): Promise<void>;
-    /**
-     * Remove a specific cache entry
-     * @param key Cache key to remove
-     */
-    delete(key: string): Promise<void>;
-}
-/**
- * In-memory cache implementation
- *
- * Suitable for:
- * - Node.js runtimes
- * - Development/testing
- * - Single-instance deployments
- *
- * NOT suitable for:
- * - Multi-instance deployments (cache not shared)
- * - Serverless environments (state not persisted)
- */
-export declare class InMemoryOAuthConfigCache implements OAuthConfigCache {
-    private cache;
-    get(key: string): Promise<OAuthConfig | null>;
-    set(key: string, value: OAuthConfig, ttl: number): Promise<void>;
-    clear(): Promise<void>;
-    delete(key: string): Promise<void>;
-}
-/**
- * No-op cache implementation (disables caching)
- *
- * Use when:
- * - You want to disable caching entirely
- * - Testing scenarios that require fresh data
- */
-export declare class NoOpOAuthConfigCache implements OAuthConfigCache {
-    get(_key: string): Promise<OAuthConfig | null>;
-    set(_key: string, _value: OAuthConfig, _ttl: number): Promise<void>;
-    clear(): Promise<void>;
-    delete(_key: string): Promise<void>;
-}
-//# sourceMappingURL=oauth-config-cache.d.ts.map

package/dist/cache/oauth-config-cache.js

@@ -1,76 +0,0 @@
-"use strict";
-/**
- * Platform-agnostic cache interface for OAuth provider configurations
- *
- * This interface allows different runtime adapters to provide their own
- * caching implementations (e.g., in-memory for Node.js, KV for Cloudflare)
- *
- * @package @kya-os/mcp-i-core
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.NoOpOAuthConfigCache = exports.InMemoryOAuthConfigCache = void 0;
-/**
- * In-memory cache implementation
- *
- * Suitable for:
- * - Node.js runtimes
- * - Development/testing
- * - Single-instance deployments
- *
- * NOT suitable for:
- * - Multi-instance deployments (cache not shared)
- * - Serverless environments (state not persisted)
- */
-class InMemoryOAuthConfigCache {
-    cache = new Map();
-    async get(key) {
-        const entry = this.cache.get(key);
-        if (!entry) {
-            return null;
-        }
-        // Check if expired
-        if (Date.now() > entry.expiresAt) {
-            this.cache.delete(key);
-            return null;
-        }
-        return entry.value;
-    }
-    async set(key, value, ttl) {
-        // If TTL is <= 0, don't store (entry would be immediately expired)
-        if (ttl <= 0) {
-            return;
-        }
-        const expiresAt = Date.now() + ttl;
-        this.cache.set(key, { value, expiresAt });
-    }
-    async clear() {
-        this.cache.clear();
-    }
-    async delete(key) {
-        this.cache.delete(key);
-    }
-}
-exports.InMemoryOAuthConfigCache = InMemoryOAuthConfigCache;
-/**
- * No-op cache implementation (disables caching)
- *
- * Use when:
- * - You want to disable caching entirely
- * - Testing scenarios that require fresh data
- */
-class NoOpOAuthConfigCache {
-    async get(_key) {
-        return null;
-    }
-    async set(_key, _value, _ttl) {
-        // No-op
-    }
-    async clear() {
-        // No-op
-    }
-    async delete(_key) {
-        // No-op
-    }
-}
-exports.NoOpOAuthConfigCache = NoOpOAuthConfigCache;
-//# sourceMappingURL=oauth-config-cache.js.map

package/dist/cache/tool-protection-cache.d.ts

@@ -1,89 +0,0 @@
-/**
- * Platform-agnostic cache interface for tool protection configurations
- *
- * This interface allows different runtime adapters to provide their own
- * caching implementations (e.g., in-memory for Node.js, KV for CloudFlare)
- *
- * @package @kya-os/mcp-i-core
- */
-import type { ToolProtectionConfig } from '../types/tool-protection.js';
-/**
- * Cache interface for storing and retrieving tool protection configurations
- */
-export interface ToolProtectionCache {
-    /**
-     * Retrieve a cached tool protection configuration
-     * @param key Cache key (typically projectId)
-     * @returns Cached config or null if not found/expired
-     */
-    get(key: string): Promise<ToolProtectionConfig | null>;
-    /**
-     * Store a tool protection configuration in cache
-     * @param key Cache key (typically projectId)
-     * @param value Tool protection configuration to cache
-     * @param ttl Time-to-live in milliseconds
-     */
-    set(key: string, value: ToolProtectionConfig, ttl: number): Promise<void>;
-    /**
-     * Clear all cached entries
-     */
-    clear(): Promise<void>;
-    /**
-     * Remove a specific cache entry
-     * @param key Cache key to remove
-     */
-    delete(key: string): Promise<void>;
-}
-/**
- * In-memory cache implementation
- *
- * Suitable for:
- * - Node.js runtimes
- * - Development/testing
- * - Single-instance deployments
- *
- * NOT suitable for:
- * - Multi-instance deployments (cache not shared)
- * - Serverless environments (state not persisted)
- */
-export declare class InMemoryToolProtectionCache implements ToolProtectionCache {
-    private cache;
-    get(key: string): Promise<ToolProtectionConfig | null>;
-    set(key: string, value: ToolProtectionConfig, ttl: number): Promise<void>;
-    clear(): Promise<void>;
-    delete(key: string): Promise<void>;
-    /**
-     * Clean up expired entries (call periodically)
-     */
-    cleanup(): void;
-    /**
-     * Get stale cache entry (including expired entries)
-     * Used for fail-safe behavior when API is unavailable
-     * This method accesses the internal cache map directly to avoid
-     * deletion of expired entries that would occur with get()
-     * @param key Cache key
-     * @returns Cached config or null if not found
-     */
-    getStale(key: string): ToolProtectionConfig | null;
-    /**
-     * Get expiration timestamp for a cache entry
-     * Used to check if stale cache is within maxStaleCacheAge
-     * @param key Cache key
-     * @returns Expiration timestamp in milliseconds, or null if not found
-     */
-    getExpiresAt(key: string): number | null;
-}
-/**
- * No-op cache implementation (disables caching)
- *
- * Use when:
- * - You want to disable caching entirely
- * - Testing scenarios that require fresh data
- */
-export declare class NoOpToolProtectionCache implements ToolProtectionCache {
-    get(_key: string): Promise<ToolProtectionConfig | null>;
-    set(_key: string, _value: ToolProtectionConfig, _ttl: number): Promise<void>;
-    clear(): Promise<void>;
-    delete(_key: string): Promise<void>;
-}
-//# sourceMappingURL=tool-protection-cache.d.ts.map

package/dist/cache/tool-protection-cache.js

@@ -1,118 +0,0 @@
-"use strict";
-/**
- * Platform-agnostic cache interface for tool protection configurations
- *
- * This interface allows different runtime adapters to provide their own
- * caching implementations (e.g., in-memory for Node.js, KV for CloudFlare)
- *
- * @package @kya-os/mcp-i-core
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.NoOpToolProtectionCache = exports.InMemoryToolProtectionCache = void 0;
-/**
- * In-memory cache implementation
- *
- * Suitable for:
- * - Node.js runtimes
- * - Development/testing
- * - Single-instance deployments
- *
- * NOT suitable for:
- * - Multi-instance deployments (cache not shared)
- * - Serverless environments (state not persisted)
- */
-class InMemoryToolProtectionCache {
-    cache = new Map();
-    async get(key) {
-        const entry = this.cache.get(key);
-        if (!entry) {
-            return null;
-        }
-        // Check if expired
-        if (Date.now() > entry.expiresAt) {
-            this.cache.delete(key);
-            return null;
-        }
-        return entry.value;
-    }
-    async set(key, value, ttl) {
-        // If TTL is <= 0, don't store (entry would be immediately expired)
-        if (ttl <= 0) {
-            return;
-        }
-        const expiresAt = Date.now() + ttl;
-        this.cache.set(key, { value, expiresAt });
-    }
-    async clear() {
-        this.cache.clear();
-    }
-    async delete(key) {
-        this.cache.delete(key);
-    }
-    /**
-     * Clean up expired entries (call periodically)
-     */
-    cleanup() {
-        const now = Date.now();
-        for (const [key, entry] of this.cache.entries()) {
-            if (now > entry.expiresAt) {
-                this.cache.delete(key);
-            }
-        }
-    }
-    /**
-     * Get stale cache entry (including expired entries)
-     * Used for fail-safe behavior when API is unavailable
-     * This method accesses the internal cache map directly to avoid
-     * deletion of expired entries that would occur with get()
-     * @param key Cache key
-     * @returns Cached config or null if not found
-     */
-    getStale(key) {
-        // Access internal cache map directly (not through async get() which deletes expired entries)
-        const entry = this.cache.get(key);
-        if (!entry) {
-            return null;
-        }
-        // Return value even if expired (getStale is meant for fail-safe behavior)
-        return entry.value;
-    }
-    /**
-     * Get expiration timestamp for a cache entry
-     * Used to check if stale cache is within maxStaleCacheAge
-     * @param key Cache key
-     * @returns Expiration timestamp in milliseconds, or null if not found
-     */
-    getExpiresAt(key) {
-        // Access internal cache map directly (not through async get() which deletes expired entries)
-        const entry = this.cache.get(key);
-        if (!entry) {
-            return null;
-        }
-        return entry.expiresAt;
-    }
-}
-exports.InMemoryToolProtectionCache = InMemoryToolProtectionCache;
-/**
- * No-op cache implementation (disables caching)
- *
- * Use when:
- * - You want to disable caching entirely
- * - Testing scenarios that require fresh data
- */
-class NoOpToolProtectionCache {
-    async get(_key) {
-        return null;
-    }
-    async set(_key, _value, _ttl) {
-        // No-op
-    }
-    async clear() {
-        // No-op
-    }
-    async delete(_key) {
-        // No-op
-    }
-}
-exports.NoOpToolProtectionCache = NoOpToolProtectionCache;
-//# sourceMappingURL=tool-protection-cache.js.map

package/dist/compliance/index.d.ts

@@ -1,8 +0,0 @@
-/**
- * Schema Compliance Module
- *
- * Automated verification against canonical schemas from schemas.kya-os.ai
- */
-export * from './schema-verifier';
-export * from './schema-registry';
-//# sourceMappingURL=index.d.ts.map