@kya-os/mcp-i-core 1.3.12 → 1.3.14

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

@@ -1,63 +0,0 @@
-/**
- * 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

@@ -1,155 +0,0 @@
-/**
- * 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

@@ -1,156 +0,0 @@
-/**
- * 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,
-  generateDidKeyFromBytes,
-  generateDidKeyFromBase64,
-} 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");
-    });
-  });
-
-  describe("generateDidKeyFromBytes", () => {
-    it("should generate valid did:key from 32-byte Ed25519 public key", () => {
-      // Use a known test key (32 bytes)
-      const publicKeyBytes = new Uint8Array(32).fill(0xab);
-      const did = generateDidKeyFromBytes(publicKeyBytes);
-
-      expect(did).toMatch(/^did:key:z6Mk/);
-      expect(isValidDid(did)).toBe(true);
-      expect(getDidMethod(did)).toBe("key");
-    });
-
-    it("should generate consistent did:key for same input", () => {
-      const publicKeyBytes = new Uint8Array(32).fill(0x42);
-      const did1 = generateDidKeyFromBytes(publicKeyBytes);
-      const did2 = generateDidKeyFromBytes(publicKeyBytes);
-
-      expect(did1).toBe(did2);
-    });
-
-    it("should generate different did:key for different inputs", () => {
-      const key1 = new Uint8Array(32).fill(0x11);
-      const key2 = new Uint8Array(32).fill(0x22);
-
-      const did1 = generateDidKeyFromBytes(key1);
-      const did2 = generateDidKeyFromBytes(key2);
-
-      expect(did1).not.toBe(did2);
-    });
-  });
-
-  describe("generateDidKeyFromBase64", () => {
-    it("should generate valid did:key from base64-encoded public key", () => {
-      // Base64 encode a 32-byte key
-      const publicKeyBytes = new Uint8Array(32).fill(0xcd);
-      const publicKeyBase64 = btoa(String.fromCharCode(...publicKeyBytes));
-
-      const did = generateDidKeyFromBase64(publicKeyBase64);
-
-      expect(did).toMatch(/^did:key:z6Mk/);
-      expect(isValidDid(did)).toBe(true);
-    });
-
-    it("should produce same result as generateDidKeyFromBytes", () => {
-      const publicKeyBytes = new Uint8Array(32).fill(0xef);
-      const publicKeyBase64 = btoa(String.fromCharCode(...publicKeyBytes));
-
-      const didFromBytes = generateDidKeyFromBytes(publicKeyBytes);
-      const didFromBase64 = generateDidKeyFromBase64(publicKeyBase64);
-
-      expect(didFromBytes).toBe(didFromBase64);
-    });
-  });
-});
-

package/src/utils/base58.ts

@@ -1,109 +0,0 @@
-/**
- * Base58 Utilities (Bitcoin alphabet)
- *
- * Encoding and decoding utilities for Base58 (Bitcoin alphabet).
- * Used for did:key multibase encoding (with 'z' prefix for base58btc).
- *
- * The Bitcoin alphabet excludes ambiguous characters (0, O, I, l).
- */
-
-const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
-const ALPHABET_MAP = new Map<string, number>();
-
-// Build reverse lookup map
-for (let i = 0; i < ALPHABET.length; i++) {
-  ALPHABET_MAP.set(ALPHABET[i], i);
-}
-
-/**
- * Encode bytes to Base58 (Bitcoin alphabet)
- *
- * @param bytes - Bytes to encode
- * @returns Base58-encoded string
- */
-export function base58Encode(bytes: Uint8Array): string {
-  if (bytes.length === 0) return '';
-
-  // Convert bytes to big integer
-  let num = BigInt(0);
-  for (let i = 0; i < bytes.length; i++) {
-    num = num * BigInt(256) + BigInt(bytes[i]);
-  }
-
-  // Convert to base58
-  let result = '';
-  while (num > 0) {
-    result = ALPHABET[Number(num % BigInt(58))] + result;
-    num = num / BigInt(58);
-  }
-
-  // Add leading zeros (encoded as '1' in base58)
-  for (let i = 0; i < bytes.length && bytes[i] === 0; i++) {
-    result = '1' + result;
-  }
-
-  return result;
-}
-
-/**
- * Decode Base58 (Bitcoin alphabet) to bytes
- *
- * @param encoded - Base58-encoded string
- * @returns Decoded bytes
- * @throws Error if input contains invalid characters
- */
-export function base58Decode(encoded: string): Uint8Array {
-  if (encoded.length === 0) return new Uint8Array(0);
-
-  // Convert base58 to big integer
-  let num = BigInt(0);
-  for (const char of encoded) {
-    const value = ALPHABET_MAP.get(char);
-    if (value === undefined) {
-      throw new Error(`Invalid base58 character: ${char}`);
-    }
-    num = num * BigInt(58) + BigInt(value);
-  }
-
-  // Convert big integer to bytes
-  const bytes: number[] = [];
-  while (num > 0) {
-    bytes.unshift(Number(num % BigInt(256)));
-    num = num / BigInt(256);
-  }
-
-  // Count leading zeros in input (encoded as '1')
-  let leadingZeros = 0;
-  for (const char of encoded) {
-    if (char === '1') {
-      leadingZeros++;
-    } else {
-      break;
-    }
-  }
-
-  // Prepend leading zero bytes
-  const result = new Uint8Array(leadingZeros + bytes.length);
-  // Leading zeros are already 0 in Uint8Array
-  result.set(bytes, leadingZeros);
-
-  return result;
-}
-
-/**
- * Validate a Base58 string
- *
- * @param encoded - String to validate
- * @returns true if valid Base58, false otherwise
- */
-export function isValidBase58(encoded: string): boolean {
-  if (encoded.length === 0) return true;
-
-  for (const char of encoded) {
-    if (!ALPHABET_MAP.has(char)) {
-      return false;
-    }
-  }
-
-  return true;
-}

package/src/utils/base64.ts

@@ -1,148 +0,0 @@
-/**
- * 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);
-}