@kya-os/mcp-i-core 1.2.3-canary.7 → 1.3.0

package/src/types/oauth-required-error.ts

@@ -0,0 +1,63 @@
+/**
+ * OAuth Required Error
+ *
+ * Error thrown when a tool requires an IDP token (OAuth) but none is available.
+ * This triggers the OAuth flow to obtain the necessary token.
+ *
+ * @package @kya-os/mcp-i-core
+ */
+
+export interface OAuthRequiredErrorOptions {
+  /** Name of the tool requiring OAuth */
+  toolName: string;
+
+  /** Required OAuth scopes */
+  requiredScopes: string[];
+
+  /** OAuth provider name (e.g., "github", "google") */
+  provider: string;
+
+  /** OAuth authorization URL */
+  oauthUrl: string;
+
+  /** Optional resume token for continuing after OAuth */
+  resumeToken?: string;
+
+  /** Optional user DID */
+  userDid?: string;
+
+  /** Optional session ID */
+  sessionId?: string;
+}
+
+/**
+ * Error thrown when a tool requires OAuth but IDP token is not available
+ *
+ * This error should trigger the OAuth flow to obtain the necessary IDP token.
+ */
+export class OAuthRequiredError extends Error {
+  public readonly toolName: string;
+  public readonly requiredScopes: string[];
+  public readonly provider: string;
+  public readonly oauthUrl: string;
+  public readonly resumeToken?: string;
+  public readonly userDid?: string;
+  public readonly sessionId?: string;
+
+  constructor(options: OAuthRequiredErrorOptions) {
+    const { toolName, requiredScopes, provider, oauthUrl } = options;
+    super(
+      `OAuth required for tool "${toolName}" with provider "${provider}". ` +
+        `Required scopes: ${requiredScopes.join(", ")}`
+    );
+    this.name = "OAuthRequiredError";
+    this.toolName = toolName;
+    this.requiredScopes = requiredScopes;
+    this.provider = provider;
+    this.oauthUrl = oauthUrl;
+    this.resumeToken = options.resumeToken;
+    this.userDid = options.userDid;
+    this.sessionId = options.sessionId;
+  }
+}
+

package/src/types/tool-protection.ts

@@ -0,0 +1,155 @@
+/**
+ * Tool Protection Types
+ *
+ * Implementation-specific type definitions for tool protection services.
+ * Core spec types are imported from @kya-os/contracts/tool-protection.
+ *
+ * @package @kya-os/mcp-i-core
+ * @version 1.0.0
+ */
+
+// Import spec types from contracts
+import type {
+  ToolProtection,
+  ToolProtectionMap,
+} from "@kya-os/contracts/tool-protection";
+
+// Re-export for backward compatibility
+export type { ToolProtection };
+
+/**
+ * Complete tool protection configuration for a project
+ * @deprecated Use ToolProtectionMap from @kya-os/contracts/tool-protection
+ */
+export interface ToolProtectionConfig {
+  /**
+   * Map of tool names to their protection settings
+   */
+  toolProtections: ToolProtectionMap;
+}
+
+/**
+ * Configuration for the ToolProtectionService
+ */
+export interface ToolProtectionServiceConfig {
+  /**
+   * AgentShield API base URL
+   * @example "https://kya.vouched.id"
+   */
+  apiUrl: string;
+
+  /**
+   * AgentShield API key for authentication
+   * @example "sk_..."
+   */
+  apiKey: string;
+
+  /**
+   * Project ID (optional, used for backward compatibility)
+   * The service now fetches config by agent DID instead
+   * @deprecated Use agent DID from runtime identity
+   * @example "mcp-i-ieu0ro"
+   */
+  projectId?: string;
+
+  /**
+   * Cache TTL in milliseconds
+   * @default 300000 (5 minutes)
+   */
+  cacheTtl?: number;
+
+  /**
+   * Fallback configuration to use if API is unavailable
+   * @optional
+   */
+  fallbackConfig?: ToolProtectionConfig;
+
+  /**
+   * Fail-safe behavior when API is unavailable and no fallback is provided
+   * - 'deny-all': Block all tools by default (secure, recommended for production)
+   * - 'allow-all': Allow all tools (insecure, not recommended for production)
+   * @default 'deny-all'
+   */
+  failSafeBehavior?: 'deny-all' | 'allow-all';
+
+  /**
+   * Maximum age (in milliseconds) for stale cache to be used during outages
+   * Stale cache is used when API fails and no fallback is provided
+   * @default 86400000 (24 hours)
+   */
+  maxStaleCacheAge?: number;
+
+  /**
+   * Allow using stale cache during outages
+   * @default true
+   */
+  allowStaleCache?: boolean;
+
+  /**
+   * Enable debug logging
+   * @default false
+   */
+  debug?: boolean;
+}
+
+/**
+ * API response from /api/v1/bouncer/projects/{projectId}/tool-protections
+ */
+export interface ToolProtectionApiResponse {
+  success: boolean;
+  data: {
+    toolProtections: Record<string, ToolProtection>;
+  };
+  metadata: {
+    timestamp: string;
+    cachedUntil: string;
+  };
+}
+
+/**
+ * Error thrown when a tool requires delegation but none is provided
+ *
+ * Note: Resume token generation is handled by MCPIRuntimeBase.generateResumeToken().
+ * The runtime should generate the token and pass it to this constructor.
+ */
+export class DelegationRequiredError extends Error {
+  public resumeToken?: string;
+  public interceptedCall?: InterceptedToolCall;
+
+  constructor(
+    public toolName: string,
+    public requiredScopes: string[],
+    public consentUrl?: string,
+    interceptedCall?: InterceptedToolCall,
+    resumeToken?: string
+  ) {
+    super(`Delegation required for tool "${toolName}"`);
+    this.name = "DelegationRequiredError";
+    this.interceptedCall = interceptedCall;
+    this.resumeToken = resumeToken;
+  }
+}
+
+/**
+ * Context for an intercepted tool call that needs authorization
+ */
+export interface InterceptedToolCall {
+  toolName: string;
+  args: any;
+  sessionId: string;
+  timestamp: number;
+  expiresAt: number;
+}
+
+/**
+ * Error thrown when the tool protection service fails
+ */
+export class ToolProtectionServiceError extends Error {
+  constructor(
+    message: string,
+    public cause?: Error
+  ) {
+    super(message);
+    this.name = "ToolProtectionServiceError";
+  }
+}

package/src/utils/__tests__/did-helpers.test.ts

@@ -0,0 +1,101 @@
+/**
+ * Tests for DID Helper Utilities
+ *
+ * @package @kya-os/mcp-i-core/utils/__tests__
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  isValidDid,
+  getDidMethod,
+  normalizeDid,
+  compareDids,
+  getServerDid,
+} from "../did-helpers";
+
+describe("DID Helpers", () => {
+  describe("isValidDid", () => {
+    it("should return true for valid DIDs", () => {
+      expect(isValidDid("did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK")).toBe(true);
+      expect(isValidDid("did:web:example.com")).toBe(true);
+      expect(isValidDid("did:web:example.com:path")).toBe(true);
+    });
+
+    it("should return false for invalid DIDs", () => {
+      expect(isValidDid("not-a-did")).toBe(false);
+      expect(isValidDid("")).toBe(false);
+      expect(isValidDid("did")).toBe(false);
+      expect(isValidDid("key:z6Mk...")).toBe(false);
+    });
+  });
+
+  describe("getDidMethod", () => {
+    it("should extract DID method correctly", () => {
+      expect(getDidMethod("did:key:z6Mk...")).toBe("key");
+      expect(getDidMethod("did:web:example.com")).toBe("web");
+      expect(getDidMethod("did:ion:...")).toBe("ion");
+    });
+
+    it("should return null for invalid DIDs", () => {
+      expect(getDidMethod("not-a-did")).toBeNull();
+      expect(getDidMethod("")).toBeNull();
+      expect(getDidMethod("did")).toBeNull();
+    });
+  });
+
+  describe("normalizeDid", () => {
+    it("should trim whitespace", () => {
+      expect(normalizeDid("  did:key:z6Mk...  ")).toBe("did:key:z6Mk...");
+      expect(normalizeDid("did:key:z6Mk...")).toBe("did:key:z6Mk...");
+    });
+  });
+
+  describe("compareDids", () => {
+    it("should compare DIDs correctly", () => {
+      expect(compareDids("did:key:z6Mk...", "did:key:z6Mk...")).toBe(true);
+      expect(compareDids("did:key:z6Mk...", "did:web:example.com")).toBe(false);
+    });
+
+    it("should normalize before comparing", () => {
+      expect(compareDids("  did:key:z6Mk...  ", "did:key:z6Mk...")).toBe(true);
+    });
+  });
+
+  describe("getServerDid", () => {
+    it("should return serverDid when present", () => {
+      const config = {
+        identity: {
+          serverDid: "did:web:server.com",
+        },
+      };
+      expect(getServerDid(config)).toBe("did:web:server.com");
+    });
+
+    it("should return agentDid when serverDid not present (backward compatibility)", () => {
+      const config = {
+        identity: {
+          agentDid: "did:web:old-server.com",
+        },
+      };
+      expect(getServerDid(config)).toBe("did:web:old-server.com");
+    });
+
+    it("should prefer serverDid over agentDid", () => {
+      const config = {
+        identity: {
+          serverDid: "did:web:new-server.com",
+          agentDid: "did:web:old-server.com",
+        },
+      };
+      expect(getServerDid(config)).toBe("did:web:new-server.com");
+    });
+
+    it("should throw error when neither serverDid nor agentDid present", () => {
+      const config = {
+        identity: {},
+      };
+      expect(() => getServerDid(config)).toThrow("Server DID not configured");
+    });
+  });
+});
+

package/src/utils/base64.ts

@@ -0,0 +1,148 @@
+/**
+ * Base64URL Encoding/Decoding Utilities
+ *
+ * Environment-aware base64url helpers that work in both Node.js and Cloudflare Workers.
+ * Uses Buffer in Node.js, TextEncoder/Decoder fallback for Workers.
+ */
+
+/**
+ * Decode base64url string to string
+ */
+export function base64urlDecodeToString(input: string): string {
+  const padded = addPadding(input);
+  const base64 = padded.replace(/-/g, "+").replace(/_/g, "/");
+
+  // For platforms that don't have Buffer (e.g., Cloudflare Workers)
+  if (typeof atob !== "undefined") {
+    try {
+      return atob(base64);
+    } catch (error) {
+      throw new Error(
+        `Invalid base64url string: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  // For Node.js environments - Buffer.from doesn't throw for invalid base64
+  // We need to validate by checking if the input contains only valid base64 characters
+  // Base64 characters: A-Z, a-z, 0-9, +, /, = (padding)
+  const base64Regex = /^[A-Za-z0-9+/]*={0,2}$/;
+  if (!base64Regex.test(base64)) {
+    throw new Error("Invalid base64url string: contains invalid characters");
+  }
+
+  try {
+    const decoded = Buffer.from(base64, "base64").toString("utf-8");
+    return decoded;
+  } catch (error) {
+    throw new Error(
+      `Invalid base64url string: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Decode base64url string to Uint8Array
+ */
+export function base64urlDecodeToBytes(input: string): Uint8Array {
+  const padded = addPadding(input);
+  const base64 = padded.replace(/-/g, "+").replace(/_/g, "/");
+
+  // For platforms that don't have Buffer (e.g., Cloudflare Workers)
+  if (typeof atob !== "undefined") {
+    try {
+      const binaryString = atob(base64);
+      const bytes = new Uint8Array(binaryString.length);
+      for (let i = 0; i < binaryString.length; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+      }
+      return bytes;
+    } catch (error) {
+      throw new Error(
+        `Invalid base64url string: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  // For Node.js environments - Buffer.from doesn't throw, so we can't validate here
+  // The caller should validate the result if needed
+  return new Uint8Array(Buffer.from(base64, "base64"));
+}
+
+/**
+ * Encode string to base64url
+ */
+export function base64urlEncodeFromString(input: string): string {
+  // For platforms that don't have Buffer
+  if (typeof btoa !== "undefined") {
+    const base64 = btoa(input);
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+  }
+
+  // For Node.js environments
+  const base64 = Buffer.from(input, "utf-8").toString("base64");
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+
+/**
+ * Encode Uint8Array to base64url
+ */
+export function base64urlEncodeFromBytes(bytes: Uint8Array): string {
+  // For platforms that don't have Buffer
+  if (typeof btoa !== "undefined") {
+    const binaryString = Array.from(bytes)
+      .map((byte) => String.fromCharCode(byte))
+      .join("");
+    const base64 = btoa(binaryString);
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+  }
+
+  // For Node.js environments
+  const base64 = Buffer.from(bytes).toString("base64");
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+
+/**
+ * Convert bytes to standard base64 (not base64url)
+ */
+export function bytesToBase64(bytes: Uint8Array): string {
+  // For platforms that don't have Buffer
+  if (typeof btoa !== "undefined") {
+    const binaryString = Array.from(bytes)
+      .map((byte) => String.fromCharCode(byte))
+      .join("");
+    return btoa(binaryString);
+  }
+
+  // For Node.js environments
+  return Buffer.from(bytes).toString("base64");
+}
+
+/**
+ * Convert standard base64 to bytes
+ */
+export function base64ToBytes(base64: string): Uint8Array {
+  // For platforms that don't have Buffer
+  if (typeof atob !== "undefined") {
+    const binaryString = atob(base64);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes;
+  }
+
+  // For Node.js environments
+  return new Uint8Array(Buffer.from(base64, "base64"));
+}
+
+/**
+ * Add padding to base64url string if needed
+ */
+function addPadding(input: string): string {
+  const remainder = input.length % 4;
+  if (remainder === 0) {
+    return input;
+  }
+  return input + "=".repeat((4 - remainder) % 4);
+}

package/src/utils/cors.ts

@@ -0,0 +1,83 @@
+/**
+ * CORS Header Utilities
+ *
+ * Centralized CORS header management for MCP-I services.
+ * Includes Vary: Origin for cache optimization when origin scoping is implemented.
+ */
+
+/**
+ * Type-safe CORS headers
+ * Compatible with Response headers and HeadersInit
+ */
+export type CORSHeaders = Record<string, string>;
+
+/**
+ * Standard CORS headers for well-known endpoints (.well-known/*)
+ * Includes Vary: Origin for future cache optimization when origin scoping is added
+ */
+export const WELL_KNOWN_CORS_HEADERS: CORSHeaders = {
+  'Access-Control-Allow-Origin': '*',
+  'Vary': 'Origin'
+};
+
+/**
+ * CORS headers for MCP protocol responses
+ * Includes exposed headers for session management
+ */
+export const MCP_CORS_HEADERS: CORSHeaders = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Expose-Headers': 'mcp-session-id',
+  'Vary': 'Origin'
+};
+
+/**
+ * CORS preflight headers for OPTIONS requests
+ * Comprehensive header allowlist for MCP protocol
+ */
+export const PREFLIGHT_CORS_HEADERS: CORSHeaders = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type, Authorization, mcp-session-id, mcp-protocol-version',
+  'Vary': 'Origin'
+};
+
+/**
+ * CORS headers for OAuth endpoints
+ * Includes additional headers required for OAuth 2.0 flows
+ */
+export const OAUTH_CORS_HEADERS: CORSHeaders = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type, Authorization, Accept, mcp-protocol-version',
+  'Access-Control-Expose-Headers': 'Content-Type',
+  'Vary': 'Origin'
+};
+
+/**
+ * Merge CORS headers with existing headers
+ * Ensures CORS headers take precedence
+ */
+export function mergeCORSHeaders(
+  existingHeaders: Record<string, string>,
+  corsHeaders: CORSHeaders = WELL_KNOWN_CORS_HEADERS
+): Record<string, string> {
+  return {
+    ...existingHeaders,
+    ...corsHeaders
+  };
+}
+
+/**
+ * Apply CORS headers to an Express Response object
+ * For use with Express middleware
+ */
+export function applyCORSHeaders(
+  res: { setHeader: (name: string, value: string) => void },
+  corsHeaders: CORSHeaders = MCP_CORS_HEADERS
+): void {
+  Object.entries(corsHeaders).forEach(([key, value]) => {
+    if (value !== undefined) {
+      res.setHeader(key, value);
+    }
+  });
+}

package/src/utils/did-helpers.ts

@@ -0,0 +1,150 @@
+/**
+ * DID Validation and Helper Utilities
+ *
+ * Centralized utilities for DID validation, normalization, and handling.
+ * Promotes DRY principle and consistency across the codebase.
+ *
+ * @package @kya-os/mcp-i-core/utils
+ */
+
+/**
+ * Check if a string is a valid DID format
+ *
+ * @param did - String to validate
+ * @returns true if string starts with "did:"
+ *
+ * @example
+ * ```typescript
+ * isValidDid("did:key:z6Mk...") // true
+ * isValidDid("not-a-did") // false
+ * ```
+ */
+export function isValidDid(did: string): boolean {
+  return typeof did === "string" && did.startsWith("did:");
+}
+
+/**
+ * Get the DID method from a DID string
+ *
+ * @param did - DID string
+ * @returns DID method (e.g., "key", "web") or null if invalid
+ *
+ * @example
+ * ```typescript
+ * getDidMethod("did:key:z6Mk...") // "key"
+ * getDidMethod("did:web:example.com") // "web"
+ * getDidMethod("invalid") // null
+ * ```
+ */
+export function getDidMethod(did: string): string | null {
+  if (!isValidDid(did)) {
+    return null;
+  }
+  const match = did.match(/^did:([^:]+):/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Normalize a DID string (trim whitespace)
+ *
+ * @param did - DID string to normalize
+ * @returns Normalized DID string
+ *
+ * @example
+ * ```typescript
+ * normalizeDid("  did:key:z6Mk...  ") // "did:key:z6Mk..."
+ * ```
+ */
+export function normalizeDid(did: string): string {
+  return did.trim();
+}
+
+/**
+ * Compare two DIDs for equality (case-sensitive)
+ *
+ * @param did1 - First DID
+ * @param did2 - Second DID
+ * @returns true if DIDs are equal (after normalization)
+ *
+ * @example
+ * ```typescript
+ * compareDids("did:key:z6Mk...", "did:key:z6Mk...") // true
+ * compareDids("did:key:z6Mk...", "did:web:example.com") // false
+ * ```
+ */
+export function compareDids(did1: string, did2: string): boolean {
+  return normalizeDid(did1) === normalizeDid(did2);
+}
+
+/**
+ * Extract server DID from config (supports both old and new field names)
+ *
+ * Supports backward compatibility by reading both `serverDid` and deprecated `agentDid`.
+ * Prefers `serverDid` if both are present.
+ *
+ * @param config - Config object with identity field
+ * @returns Server DID string
+ * @throws Error if neither serverDid nor agentDid is configured
+ *
+ * @example
+ * ```typescript
+ * // New config
+ * getServerDid({ identity: { serverDid: "did:web:server.com" } }) // "did:web:server.com"
+ *
+ * // Old config (backward compatibility)
+ * getServerDid({ identity: { agentDid: "did:web:server.com" } }) // "did:web:server.com"
+ *
+ * // Prefers serverDid over agentDid
+ * getServerDid({ identity: { serverDid: "new", agentDid: "old" } }) // "new"
+ * ```
+ */
+export function getServerDid(config: {
+  identity: { serverDid?: string; agentDid?: string };
+}): string {
+  const serverDid = config.identity.serverDid || config.identity.agentDid;
+  if (!serverDid) {
+    throw new Error("Server DID not configured");
+  }
+  return serverDid;
+}
+
+/**
+ * Extract agent ID from DID
+ *
+ * The agent ID is the last component of the DID.
+ *
+ * @param did - DID string
+ * @returns Agent ID (last component of DID)
+ *
+ * @example
+ * ```typescript
+ * extractAgentId("did:web:knowthat.ai:agents:my-agent") // "my-agent"
+ * extractAgentId("did:web:localhost:3000:agents:12912feb") // "12912feb"
+ * extractAgentId("did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK") // "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
+ * ```
+ */
+export function extractAgentId(did: string): string {
+  const parts = did.split(':');
+  return parts[parts.length - 1];
+}
+
+/**
+ * Extract agent slug from DID
+ *
+ * Agent slug is the same as agent ID - the last component of the DID.
+ * For DID format: did:web:knowthat.ai:agents:my-agent
+ * Returns: my-agent
+ *
+ * @param did - DID string
+ * @returns Agent slug (last component of DID)
+ *
+ * @example
+ * ```typescript
+ * extractAgentSlug("did:web:knowthat.ai:agents:my-agent") // "my-agent"
+ * extractAgentSlug("did:web:localhost:3000:agents:12912feb") // "12912feb"
+ * ```
+ */
+export function extractAgentSlug(did: string): string {
+  return extractAgentId(did);
+}
+

package/src/utils/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Utility exports
+ */
+
+export * from "./cors";
+export * from "./base64";
+export * from "./storage-keys";
+export * from "./did-helpers";