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

package/src/__tests__/utils/mock-providers.ts

@@ -0,0 +1,340 @@
+/**
+ * Mock Providers for Testing
+ * 
+ * These mock implementations allow controlled testing of the runtime
+ * and other components that depend on providers.
+ */
+
+import { vi } from 'vitest';
+import {
+  CryptoProvider,
+  ClockProvider,
+  FetchProvider,
+  StorageProvider,
+  NonceCacheProvider,
+  IdentityProvider,
+  AgentIdentity
+} from '../../providers/base';
+
+/**
+ * Mock Crypto Provider
+ */
+export class MockCryptoProvider extends CryptoProvider {
+  async sign(data: Uint8Array, privateKey: string): Promise<Uint8Array> {
+    // Simple mock signature
+    return new Uint8Array([1, 2, 3, 4, 5]);
+  }
+
+  async verify(data: Uint8Array, signature: Uint8Array, publicKey: string): Promise<boolean> {
+    // Simple verification - check signature matches expected pattern
+    // In real implementation, this would verify cryptographic signature
+    return signature.length === 5 && signature[0] === 1 && signature[1] === 2;
+  }
+
+  async generateKeyPair(): Promise<{ privateKey: string; publicKey: string }> {
+    // Generate valid base64-encoded keys for testing
+    // Ed25519 keys are 32 bytes, so we generate 32 random bytes and encode them
+    const randomBytes = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+      randomBytes[i] = Math.floor(Math.random() * 256);
+    }
+    
+    // Convert to base64 using Node.js Buffer (works in Node.js test environment)
+    const base64PrivateKey = Buffer.from(randomBytes).toString('base64');
+    
+    // Generate a different public key (Ed25519 public key is also 32 bytes)
+    const publicBytes = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+      publicBytes[i] = Math.floor(Math.random() * 256);
+    }
+    const base64PublicKey = Buffer.from(publicBytes).toString('base64');
+    
+    return {
+      privateKey: base64PrivateKey,
+      publicKey: base64PublicKey
+    };
+  }
+
+  async hash(data: Uint8Array): Promise<Uint8Array> {
+    // Simple mock hash
+    return new Uint8Array([9, 8, 7, 6, 5]);
+  }
+
+  async randomBytes(length: number): Promise<Uint8Array> {
+    const bytes = new Uint8Array(length);
+    for (let i = 0; i < length; i++) {
+      bytes[i] = Math.floor(Math.random() * 256);
+    }
+    return bytes;
+  }
+}
+
+/**
+ * Mock Clock Provider
+ */
+export class MockClockProvider extends ClockProvider {
+  private currentTime: number = Date.now();
+
+  setTime(timestamp: number): void {
+    this.currentTime = timestamp;
+  }
+
+  now(): number {
+    return this.currentTime;
+  }
+
+  isWithinSkew(timestamp: number, skewSeconds: number): boolean {
+    const diff = Math.abs(this.currentTime - timestamp);
+    return diff <= skewSeconds * 1000;
+  }
+
+  hasExpired(expiresAt: number): boolean {
+    return this.currentTime > expiresAt;
+  }
+
+  calculateExpiry(ttlSeconds: number): number {
+    return this.currentTime + (ttlSeconds * 1000);
+  }
+
+  format(timestamp: number): string {
+    return new Date(timestamp).toISOString();
+  }
+}
+
+/**
+ * Mock Fetch Provider
+ */
+export class MockFetchProvider extends FetchProvider {
+  private didDocuments: Map<string, any> = new Map();
+  private statusLists: Map<string, any> = new Map();
+  private delegationChains: Map<string, any[]> = new Map();
+  public fetch: (url: string, options?: any) => Promise<Response>;
+
+  constructor() {
+    super();
+    // Initialize fetch as a vi.fn() in constructor to ensure it's always mockable
+    this.fetch = vi.fn(async (url: string, options?: any): Promise<Response> => {
+      // Simple mock Response
+      return new Response(JSON.stringify({ url, options }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' }
+      });
+    }) as any;
+  }
+
+  // Test helpers
+  setDIDDocument(did: string, doc: any): void {
+    this.didDocuments.set(did, doc);
+  }
+
+  setStatusList(url: string, list: any): void {
+    this.statusLists.set(url, list);
+  }
+
+  setDelegationChain(id: string, chain: any[]): void {
+    this.delegationChains.set(id, chain);
+  }
+
+  async resolveDID(did: string): Promise<any> {
+    const doc = this.didDocuments.get(did);
+    if (!doc) {
+      throw new Error(`DID ${did} not found`);
+    }
+    return doc;
+  }
+
+  async fetchStatusList(url: string): Promise<any> {
+    const list = this.statusLists.get(url);
+    if (!list) {
+      throw new Error(`Status list ${url} not found`);
+    }
+    return list;
+  }
+
+  async fetchDelegationChain(id: string): Promise<any[]> {
+    const chain = this.delegationChains.get(id);
+    if (!chain) {
+      throw new Error(`Delegation chain ${id} not found`);
+    }
+    return chain;
+  }
+}
+
+/**
+ * Mock Storage Provider
+ */
+export class MockStorageProvider extends StorageProvider {
+  private store: Map<string, string> = new Map();
+
+  async get(key: string): Promise<string | null> {
+    return this.store.get(key) || null;
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    this.store.set(key, value);
+  }
+
+  async delete(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+
+  async exists(key: string): Promise<boolean> {
+    return this.store.has(key);
+  }
+
+  async list(prefix?: string): Promise<string[]> {
+    const keys = Array.from(this.store.keys());
+    if (prefix) {
+      return keys.filter(k => k.startsWith(prefix));
+    }
+    return keys;
+  }
+
+  // Test helper
+  clear(): void {
+    this.store.clear();
+  }
+}
+
+/**
+ * Mock Nonce Cache Provider
+ */
+export class MockNonceCacheProvider extends NonceCacheProvider {
+  private nonces: Map<string, number> = new Map();
+  public cleanupCalled = false;
+  public destroyCalled = false;
+  private clock?: ClockProvider;
+
+  setClock(clock: ClockProvider): void {
+    this.clock = clock;
+  }
+
+  async has(nonce: string, agentDid?: string): Promise<boolean> {
+    const key = agentDid ? `nonce:${agentDid}:${nonce}` : `nonce:${nonce}`;
+    const expiry = this.nonces.get(key);
+    if (!expiry) return false;
+    
+    const now = this.clock ? this.clock.now() : Date.now();
+    if (now > expiry) {
+      this.nonces.delete(key);
+      return false;
+    }
+    
+    return true;
+  }
+
+  async add(nonce: string, ttlSeconds: number, agentDid?: string): Promise<void> {
+    const key = agentDid ? `nonce:${agentDid}:${nonce}` : `nonce:${nonce}`;
+    // Convert TTL seconds to absolute expiration timestamp for storage
+    const now = this.clock ? this.clock.now() : Date.now();
+    const expiresAt = now + (ttlSeconds * 1000);
+    this.nonces.set(key, expiresAt);
+  }
+
+  async cleanup(): Promise<void> {
+    this.cleanupCalled = true;
+    const now = this.clock ? this.clock.now() : Date.now();
+    for (const [nonce, expiry] of this.nonces) {
+      if (now > expiry) {
+        this.nonces.delete(nonce);
+      }
+    }
+  }
+
+  async destroy(): Promise<void> {
+    this.destroyCalled = true;
+    this.nonces.clear();
+  }
+
+  // Test helper
+  clear(): void {
+    this.nonces.clear();
+  }
+
+  size(): number {
+    return this.nonces.size;
+  }
+}
+
+/**
+ * Mock Identity Provider
+ */
+export class MockIdentityProvider extends IdentityProvider {
+  private identity?: AgentIdentity;
+  public rotateKeysCalled = false;
+  public deleteIdentityCalled = false;
+  private rotateCount = 0;
+
+  constructor(identity?: AgentIdentity) {
+    super();
+    this.identity = identity;
+  }
+
+  async getIdentity(): Promise<AgentIdentity> {
+    if (!this.identity) {
+      this.identity = {
+        did: 'did:key:zmock123',
+        kid: 'did:key:zmock123#key-1',
+        privateKey: 'mock-private-key',
+        publicKey: 'mock-public-key',
+        createdAt: new Date().toISOString(),
+        type: 'development',
+        metadata: { mock: true }
+      };
+    }
+    return this.identity;
+  }
+
+  async saveIdentity(identity: AgentIdentity): Promise<void> {
+    this.identity = identity;
+  }
+
+  async rotateKeys(): Promise<AgentIdentity> {
+    this.rotateKeysCalled = true;
+    this.rotateCount++;
+    this.identity = {
+      did: `did:key:zmock456-${this.rotateCount}`,
+      kid: `did:key:zmock456-${this.rotateCount}#key-1`,
+      privateKey: `mock-private-key-rotated-${this.rotateCount}`,
+      publicKey: `mock-public-key-rotated-${this.rotateCount}`,
+      createdAt: new Date().toISOString(),
+      type: 'development',
+      metadata: { mock: true, rotated: true, rotateCount: this.rotateCount }
+    };
+    return this.identity;
+  }
+
+  async deleteIdentity(): Promise<void> {
+    this.deleteIdentityCalled = true;
+    this.identity = undefined;
+  }
+
+  // Test helper
+  setIdentity(identity: AgentIdentity): void {
+    this.identity = identity;
+  }
+}
+
+/**
+ * Create a full set of mock providers for testing
+ */
+export function createMockProviders() {
+  const cryptoProvider = new MockCryptoProvider();
+  const clockProvider = new MockClockProvider();
+  const fetchProvider = new MockFetchProvider();
+  const storageProvider = new MockStorageProvider();
+  const nonceCacheProvider = new MockNonceCacheProvider();
+  const identityProvider = new MockIdentityProvider();
+  
+  // Connect nonce cache to clock for consistent time
+  nonceCacheProvider.setClock(clockProvider);
+  
+  return {
+    cryptoProvider,
+    clockProvider,
+    fetchProvider,
+    storageProvider,
+    nonceCacheProvider,
+    identityProvider
+  };
+}

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

@@ -0,0 +1,69 @@
+/**
+ * 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/src/cache/oauth-config-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-config-cache.d.ts","sourceRoot":"","sources":["oauth-config-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAE9C;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjE;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,wBAAyB,YAAW,gBAAgB;IAC/D,OAAO,CAAC,KAAK,CAGT;IAEE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAgB7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAShE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGzC;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,YAAW,gBAAgB;IACrD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAI9C,GAAG,CACP,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC;IAIV,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG1C"}

package/src/cache/oauth-config-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-config-cache.js","sourceRoot":"","sources":["oauth-config-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmCH;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,wBAAwB;IAC3B,KAAK,GAAG,IAAI,GAAG,EAGpB,CAAC;IAEJ,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAElC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACd,CAAC;QAED,mBAAmB;QACnB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAkB,EAAE,GAAW;QACpD,mEAAmE;QACnE,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;YACb,OAAO;QACT,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC;QACnC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,oBAAoB;IAC/B,KAAK,CAAC,GAAG,CAAC,IAAY;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,GAAG,CACP,IAAY,EACZ,MAAmB,EACnB,IAAY;QAEZ,QAAQ;IACV,CAAC;IAED,KAAK,CAAC,KAAK;QACT,QAAQ;IACV,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAY;QACvB,QAAQ;IACV,CAAC;CACF"}

package/src/cache/oauth-config-cache.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 class InMemoryOAuthConfigCache implements OAuthConfigCache {
+  private cache = new Map<
+    string,
+    { value: OAuthConfig; expiresAt: number }
+  >();
+
+  async get(key: string): Promise<OAuthConfig | null> {
+    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: string, value: OAuthConfig, ttl: number): Promise<void> {
+    // 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(): Promise<void> {
+    this.cache.clear();
+  }
+
+  async delete(key: string): Promise<void> {
+    this.cache.delete(key);
+  }
+}
+
+/**
+ * No-op cache implementation (disables caching)
+ *
+ * Use when:
+ * - You want to disable caching entirely
+ * - Testing scenarios that require fresh data
+ */
+export class NoOpOAuthConfigCache implements OAuthConfigCache {
+  async get(_key: string): Promise<OAuthConfig | null> {
+    return null;
+  }
+
+  async set(
+    _key: string,
+    _value: OAuthConfig,
+    _ttl: number
+  ): Promise<void> {
+    // No-op
+  }
+
+  async clear(): Promise<void> {
+    // No-op
+  }
+
+  async delete(_key: string): Promise<void> {
+    // No-op
+  }
+}
+

package/src/cache/tool-protection-cache.ts

@@ -0,0 +1,171 @@
+/**
+ * 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 class InMemoryToolProtectionCache implements ToolProtectionCache {
+  private cache = new Map<
+    string,
+    { value: ToolProtectionConfig; expiresAt: number }
+  >();
+
+  async get(key: string): Promise<ToolProtectionConfig | null> {
+    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: string,
+    value: ToolProtectionConfig,
+    ttl: number
+  ): Promise<void> {
+    // 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(): Promise<void> {
+    this.cache.clear();
+  }
+
+  async delete(key: string): Promise<void> {
+    this.cache.delete(key);
+  }
+
+  /**
+   * Clean up expired entries (call periodically)
+   */
+  cleanup(): void {
+    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: string): ToolProtectionConfig | null {
+    // 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: string): number | null {
+    // 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;
+  }
+}
+
+/**
+ * No-op cache implementation (disables caching)
+ *
+ * Use when:
+ * - You want to disable caching entirely
+ * - Testing scenarios that require fresh data
+ */
+export class NoOpToolProtectionCache implements ToolProtectionCache {
+  async get(_key: string): Promise<ToolProtectionConfig | null> {
+    return null;
+  }
+
+  async set(
+    _key: string,
+    _value: ToolProtectionConfig,
+    _ttl: number
+  ): Promise<void> {
+    // No-op
+  }
+
+  async clear(): Promise<void> {
+    // No-op
+  }
+
+  async delete(_key: string): Promise<void> {
+    // No-op
+  }
+}