@mcp-ts/sdk 1.0.0

package/src/server/mcp/storage-oauth-provider.ts

@@ -0,0 +1,239 @@
+
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type {
+    OAuthClientInformation,
+    OAuthClientInformationFull,
+    OAuthClientMetadata,
+    OAuthTokens
+} from "@modelcontextprotocol/sdk/shared/auth.js";
+import { storage, SessionData } from "../storage/index.js";
+import { TOKEN_EXPIRY_BUFFER_MS } from '../../shared/constants.js';
+
+/**
+ * Extension of OAuthClientProvider interface with additional methods
+ * Enables server-specific tracking and state management
+ */
+export interface AgentsOAuthProvider extends OAuthClientProvider {
+    authUrl: string | undefined;
+    clientId: string | undefined;
+    serverId: string | undefined;
+    checkState(
+        state: string
+    ): Promise<{ valid: boolean; serverId?: string; error?: string }>;
+    consumeState(state: string): Promise<void>;
+    deleteCodeVerifier(): Promise<void>;
+    isTokenExpired(): boolean;
+    setTokenExpiresAt(expiresAt: number): void;
+}
+
+/**
+ * Storage-backed OAuth provider implementation for MCP
+ * Stores OAuth tokens, client information, and PKCE verifiers using the configured StorageBackend
+ */
+export class StorageOAuthClientProvider implements AgentsOAuthProvider {
+    private _authUrl: string | undefined;
+    private _clientId: string | undefined;
+    private onRedirectCallback?: (url: string) => void;
+    private tokenExpiresAt?: number;
+
+    /**
+     * Creates a new Storage-backed OAuth provider
+     * @param identity - User/Client identifier
+     * @param serverId - Server identifier (for tracking which server this OAuth session belongs to)
+     * @param sessionId - Session identifier (used as OAuth state)
+     * @param clientName - OAuth client name
+     * @param baseRedirectUrl - OAuth callback URL
+     * @param onRedirect - Optional callback when redirect to authorization is needed
+     */
+    constructor(
+        public identity: string,
+        public serverId: string,
+        public sessionId: string,
+        public clientName: string,
+        public baseRedirectUrl: string,
+        onRedirect?: (url: string) => void
+    ) {
+        this.onRedirectCallback = onRedirect;
+    }
+
+    get clientMetadata(): OAuthClientMetadata {
+        return {
+            client_name: this.clientName,
+            client_uri: this.clientUri,
+            grant_types: ["authorization_code", "refresh_token"],
+            redirect_uris: [this.redirectUrl],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+            ...(this._clientId ? { client_id: this._clientId } : {})
+        };
+    }
+
+    get clientUri() {
+        return new URL(this.redirectUrl).origin;
+    }
+
+    get redirectUrl() {
+        return this.baseRedirectUrl;
+    }
+
+    get clientId() {
+        return this._clientId;
+    }
+
+    set clientId(clientId_: string | undefined) {
+        this._clientId = clientId_;
+    }
+
+    /**
+     * Loads OAuth data from storage session
+     * @private
+     */
+    private async getSessionData(): Promise<SessionData> {
+        const data = await storage.getSession(this.identity, this.sessionId);
+        if (!data) {
+            // Return empty/partial object if not found
+            return {} as SessionData;
+        }
+        return data;
+    }
+
+    /**
+     * Saves OAuth data to storage
+     * @param data - Partial OAuth data to save
+     * @private
+     * @throws Error if session doesn't exist (session must be created by controller layer)
+     */
+    private async saveSessionData(data: Partial<SessionData>): Promise<void> {
+        await storage.updateSession(this.identity, this.sessionId, data);
+    }
+
+    /**
+     * Retrieves stored OAuth client information
+     */
+    async clientInformation(): Promise<OAuthClientInformation | undefined> {
+        const data = await this.getSessionData();
+
+        if (data.clientId && !this._clientId) {
+            this._clientId = data.clientId;
+        }
+
+        return data.clientInformation;
+    }
+
+    /**
+     * Stores OAuth client information
+     */
+    async saveClientInformation(clientInformation: OAuthClientInformationFull): Promise<void> {
+        await this.saveSessionData({
+            clientInformation,
+            clientId: clientInformation.client_id
+        });
+        this.clientId = clientInformation.client_id;
+    }
+
+    /**
+     * Stores OAuth tokens
+     */
+    async saveTokens(tokens: OAuthTokens): Promise<void> {
+        const data: Partial<SessionData> = { tokens };
+
+        if (tokens.expires_in) {
+            this.tokenExpiresAt = Date.now() + (tokens.expires_in * 1000) - TOKEN_EXPIRY_BUFFER_MS;
+        }
+
+        await this.saveSessionData(data);
+    }
+
+    get authUrl() {
+        return this._authUrl;
+    }
+
+    async state(): Promise<string> {
+        return this.sessionId;
+    }
+
+    async checkState(state: string): Promise<{ valid: boolean; serverId?: string; error?: string }> {
+        const data = await storage.getSession(this.identity, this.sessionId);
+
+        if (!data) {
+            return { valid: false, error: "Session not found" };
+        }
+
+        return { valid: true, serverId: this.serverId };
+    }
+
+    async consumeState(state: string): Promise<void> {
+        // No-op
+    }
+
+    async redirectToAuthorization(authUrl: URL): Promise<void> {
+        this._authUrl = authUrl.toString();
+        if (this.onRedirectCallback) {
+            this.onRedirectCallback(authUrl.toString());
+        }
+    }
+
+    async invalidateCredentials(
+        scope: "all" | "client" | "tokens" | "verifier"
+    ): Promise<void> {
+        if (scope === "all") {
+            await storage.removeSession(this.identity, this.sessionId);
+        } else {
+            const data = await this.getSessionData();
+            // Create a copy to modify
+            const updates: Partial<SessionData> = {};
+
+            if (scope === "client") {
+                updates.clientInformation = undefined;
+                updates.clientId = undefined;
+            } else if (scope === "tokens") {
+                updates.tokens = undefined;
+            } else if (scope === "verifier") {
+                updates.codeVerifier = undefined;
+            }
+            await this.saveSessionData(updates);
+        }
+    }
+
+    async saveCodeVerifier(verifier: string): Promise<void> {
+        await this.saveSessionData({ codeVerifier: verifier });
+    }
+
+    async codeVerifier(): Promise<string> {
+        const data = await this.getSessionData();
+
+        if (data.clientId && !this._clientId) {
+            this._clientId = data.clientId;
+        }
+
+        if (!data.codeVerifier) {
+            throw new Error("No code verifier found");
+        }
+        return data.codeVerifier;
+    }
+
+    async deleteCodeVerifier(): Promise<void> {
+        await this.saveSessionData({ codeVerifier: undefined });
+    }
+
+    async tokens(): Promise<OAuthTokens | undefined> {
+        const data = await this.getSessionData();
+
+        if (data.clientId && !this._clientId) {
+            this._clientId = data.clientId;
+        }
+
+        return data.tokens;
+    }
+
+    isTokenExpired(): boolean {
+        if (!this.tokenExpiresAt) {
+            return false;
+        }
+        return Date.now() >= this.tokenExpiresAt;
+    }
+
+    setTokenExpiresAt(expiresAt: number): void {
+        this.tokenExpiresAt = expiresAt;
+    }
+}

package/src/server/storage/file-backend.ts

@@ -0,0 +1,169 @@
+
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { customAlphabet } from 'nanoid';
+import { StorageBackend, SessionData, SetClientOptions } from './types';
+
+// first char: letters only (required by OpenAI)
+const firstChar = customAlphabet(
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
+    1
+);
+
+// remaining chars: alphanumeric
+const rest = customAlphabet(
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789',
+    11
+);
+
+/**
+ * File system implementation of StorageBackend
+ * Persists sessions to a JSON file
+ */
+export class FileStorageBackend implements StorageBackend {
+    private filePath: string;
+    private memoryCache: Map<string, SessionData> | null = null;
+    private initialized = false;
+
+    /**
+     * @param options.path Path to the JSON file storage (default: ./sessions.json)
+     */
+    constructor(options: { path?: string } = {}) {
+        this.filePath = options.path || './sessions.json';
+    }
+
+    /**
+     * Initialize storage: ensure file exists and load into memory cache
+     */
+    async init(): Promise<void> {
+        if (this.initialized) return;
+
+        try {
+            // Ensure directory exists
+            const dir = path.dirname(this.filePath);
+            await fs.mkdir(dir, { recursive: true });
+
+            // Try to read file
+            const data = await fs.readFile(this.filePath, 'utf-8');
+            const json = JSON.parse(data);
+
+            this.memoryCache = new Map();
+            if (Array.isArray(json)) {
+                json.forEach((s: SessionData) => {
+                    this.memoryCache!.set(this.getSessionKey(s.identity || 'unknown', s.sessionId), s);
+                });
+            }
+        } catch (error: any) {
+            if (error.code === 'ENOENT') {
+                // File does not exist, initialize empty
+                this.memoryCache = new Map();
+                await this.flush();
+            } else {
+                console.error('[FileStorage] Failed to load sessions:', error);
+                throw error;
+            }
+        }
+
+        this.initialized = true;
+    }
+
+    private async ensureInitialized() {
+        if (!this.initialized) await this.init();
+    }
+
+    private async flush(): Promise<void> {
+        if (!this.memoryCache) return;
+        const sessions = Array.from(this.memoryCache.values());
+        await fs.writeFile(this.filePath, JSON.stringify(sessions, null, 2), 'utf-8');
+    }
+
+    private getSessionKey(identity: string, sessionId: string): string {
+        return `${identity}:${sessionId}`;
+    }
+
+    generateSessionId(): string {
+        return firstChar() + rest();
+    }
+
+    async createSession(session: SessionData, ttl?: number): Promise<void> {
+        await this.ensureInitialized();
+        const { sessionId, identity } = session;
+        if (!sessionId || !identity) throw new Error('identity and sessionId required');
+
+        const sessionKey = this.getSessionKey(identity, sessionId);
+        if (this.memoryCache!.has(sessionKey)) {
+            throw new Error(`Session ${sessionId} already exists`);
+        }
+
+        this.memoryCache!.set(sessionKey, session);
+        await this.flush();
+        // Note: TTL is ignored in file backend - sessions don't auto-expire
+    }
+
+    async updateSession(identity: string, sessionId: string, data: Partial<SessionData>, ttl?: number): Promise<void> {
+        await this.ensureInitialized();
+        if (!identity || !sessionId) throw new Error('identity and sessionId required');
+
+        const sessionKey = this.getSessionKey(identity, sessionId);
+        const current = this.memoryCache!.get(sessionKey);
+
+        if (!current) {
+            throw new Error(`Session ${sessionId} not found`);
+        }
+
+        const updated = {
+            ...current,
+            ...data
+        };
+
+        this.memoryCache!.set(sessionKey, updated);
+        await this.flush();
+        // Note: TTL is ignored in file backend - sessions don't auto-expire
+    }
+
+    async getSession(identity: string, sessionId: string): Promise<SessionData | null> {
+        await this.ensureInitialized();
+        const sessionKey = this.getSessionKey(identity, sessionId);
+        return this.memoryCache!.get(sessionKey) || null;
+    }
+
+    async getIdentitySessionsData(identity: string): Promise<SessionData[]> {
+        await this.ensureInitialized();
+        return Array.from(this.memoryCache!.values()).filter(s => s.identity === identity);
+    }
+
+    async getIdentityMcpSessions(identity: string): Promise<string[]> {
+        await this.ensureInitialized();
+        return Array.from(this.memoryCache!.values())
+            .filter(s => s.identity === identity)
+            .map(s => s.sessionId);
+    }
+
+    async removeSession(identity: string, sessionId: string): Promise<void> {
+        await this.ensureInitialized();
+        const sessionKey = this.getSessionKey(identity, sessionId);
+        if (this.memoryCache!.delete(sessionKey)) {
+            await this.flush();
+        }
+    }
+
+    async getAllSessionIds(): Promise<string[]> {
+        await this.ensureInitialized();
+        return Array.from(this.memoryCache!.values()).map(s => s.sessionId);
+    }
+
+    async clearAll(): Promise<void> {
+        await this.ensureInitialized();
+        this.memoryCache!.clear();
+        await this.flush();
+    }
+
+    async cleanupExpiredSessions(): Promise<void> {
+        // Could implement TTL check here using createdAt
+        await this.ensureInitialized();
+    }
+
+    async disconnect(): Promise<void> {
+        // No explicit disconnect needed for file
+    }
+}

package/src/server/storage/index.ts

@@ -0,0 +1,115 @@
+
+import { RedisStorageBackend } from './redis-backend';
+import { MemoryStorageBackend } from './memory-backend';
+import { FileStorageBackend } from './file-backend';
+import type { StorageBackend } from './types';
+
+// Re-export types
+export * from './types';
+export { RedisStorageBackend, MemoryStorageBackend, FileStorageBackend };
+
+let storageInstance: StorageBackend | null = null;
+let storagePromise: Promise<StorageBackend> | null = null;
+
+async function createStorage(): Promise<StorageBackend> {
+    const type = process.env.MCP_TS_STORAGE_TYPE?.toLowerCase();
+
+    // Explicit selection
+    if (type === 'redis') {
+        if (!process.env.REDIS_URL) {
+            console.warn('[Storage] MCP_TS_STORAGE_TYPE is "redis" but REDIS_URL is missing');
+        }
+        try {
+            const { getRedis } = await import('./redis.js');
+            const redis = await getRedis();
+            console.log('[Storage] Using Redis storage (Explicit)');
+            return new RedisStorageBackend(redis);
+        } catch (error: any) {
+            console.error('[Storage] Failed to initialize Redis:', error.message);
+            console.log('[Storage] Falling back to In-Memory storage');
+            return new MemoryStorageBackend();
+        }
+    }
+
+    if (type === 'file') {
+        const filePath = process.env.MCP_TS_STORAGE_FILE;
+        if (!filePath) {
+            console.warn('[Storage] MCP_TS_STORAGE_TYPE is "file" but MCP_TS_STORAGE_FILE is missing');
+        }
+        console.log(`[Storage] Using File storage (${filePath}) (Explicit)`);
+        const store = new FileStorageBackend({ path: filePath });
+        store.init().catch(err => console.error('[Storage] Failed to initialize file storage:', err));
+        return store;
+    }
+
+    if (type === 'memory') {
+        console.log('[Storage] Using In-Memory storage (Explicit)');
+        return new MemoryStorageBackend();
+    }
+
+    // Automatic inference (Fallback)
+    if (process.env.REDIS_URL) {
+        try {
+            const { getRedis } = await import('./redis.js');
+            const redis = await getRedis();
+            console.log('[Storage] Auto-detected REDIS_URL. Using Redis storage.');
+            return new RedisStorageBackend(redis);
+        } catch (error: any) {
+            console.error('[Storage] Redis auto-detection failed:', error.message);
+            console.log('[Storage] Falling back to In-Memory storage');
+            return new MemoryStorageBackend();
+        }
+    }
+
+    if (process.env.MCP_TS_STORAGE_FILE) {
+        console.log(`[Storage] Auto-detected MCP_TS_STORAGE_FILE. Using File storage (${process.env.MCP_TS_STORAGE_FILE}).`);
+        const store = new FileStorageBackend({ path: process.env.MCP_TS_STORAGE_FILE });
+        store.init().catch(err => console.error('[Storage] Failed to initialize file storage:', err));
+        return store;
+    }
+
+    console.log('[Storage] No storage configured. Using In-Memory storage (Default).');
+    return new MemoryStorageBackend();
+}
+
+async function getStorage(): Promise<StorageBackend> {
+    if (storageInstance) {
+        return storageInstance;
+    }
+
+    if (!storagePromise) {
+        storagePromise = createStorage();
+    }
+
+    storageInstance = await storagePromise;
+    return storageInstance;
+}
+
+/**
+ * Set the storage instance (for testing)
+ * @internal
+ * @param instance - StorageBackend instance or null to reset
+ */
+export function _setStorageInstanceForTesting(instance: StorageBackend | null): void {
+    storageInstance = instance;
+    if (!instance) {
+        storagePromise = null;
+    }
+}
+
+/**
+ * Global session store instance
+ * Uses lazy initialization with a Proxy to handle async setup transparently
+ */
+export const storage: StorageBackend = new Proxy({} as StorageBackend, {
+    get(_target, prop) {
+        return async (...args: any[]) => {
+            const instance = await getStorage();
+            const value = (instance as any)[prop];
+            if (typeof value === 'function') {
+                return value.apply(instance, args);
+            }
+            return value;
+        };
+    },
+});

package/src/server/storage/memory-backend.ts

@@ -0,0 +1,132 @@
+
+import { customAlphabet } from 'nanoid';
+import { StorageBackend, SessionData, SetClientOptions } from './types';
+
+// first char: letters only (required by OpenAI)
+const firstChar = customAlphabet(
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
+    1
+);
+
+// remaining chars: alphanumeric
+const rest = customAlphabet(
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789',
+    11
+);
+
+/**
+ * In-memory implementation of StorageBackend
+ * Useful for local development or testing
+ */
+export class MemoryStorageBackend implements StorageBackend {
+    // Map<identity:sessionId, SessionData>
+    private sessions = new Map<string, SessionData>();
+
+    // Map<identity, Set<sessionId>>
+    private identitySessions = new Map<string, Set<string>>();
+
+    constructor() { }
+
+    private getSessionKey(identity: string, sessionId: string): string {
+        return `${identity}:${sessionId}`;
+    }
+
+    generateSessionId(): string {
+        return firstChar() + rest();
+    }
+
+    async createSession(session: SessionData, ttl?: number): Promise<void> {
+        const { sessionId, identity } = session;
+        if (!sessionId || !identity) throw new Error('identity and sessionId required');
+
+        const sessionKey = this.getSessionKey(identity, sessionId);
+        if (this.sessions.has(sessionKey)) {
+            throw new Error(`Session ${sessionId} already exists`);
+        }
+
+        this.sessions.set(sessionKey, session);
+
+        // Update index
+        if (!this.identitySessions.has(identity)) {
+            this.identitySessions.set(identity, new Set());
+        }
+        this.identitySessions.get(identity)!.add(sessionId);
+        // Note: TTL is ignored in memory backend - sessions don't auto-expire
+    }
+
+    async updateSession(identity: string, sessionId: string, data: Partial<SessionData>, ttl?: number): Promise<void> {
+        if (!identity || !sessionId) throw new Error('identity and sessionId required');
+
+        const sessionKey = this.getSessionKey(identity, sessionId);
+        const current = this.sessions.get(sessionKey);
+
+        if (!current) {
+            throw new Error(`Session ${sessionId} not found`);
+        }
+
+        const updated = {
+            ...current,
+            ...data
+        };
+
+        this.sessions.set(sessionKey, updated);
+        // Note: TTL is ignored in memory backend - sessions don't auto-expire
+    }
+
+
+    async getSession(identity: string, sessionId: string): Promise<SessionData | null> {
+        const sessionKey = this.getSessionKey(identity, sessionId);
+        return this.sessions.get(sessionKey) || null;
+    }
+
+    async getIdentityMcpSessions(identity: string): Promise<string[]> {
+        const set = this.identitySessions.get(identity);
+        return set ? Array.from(set) : [];
+    }
+
+    async getIdentitySessionsData(identity: string): Promise<SessionData[]> {
+        const set = this.identitySessions.get(identity);
+        if (!set) return [];
+
+        const results: SessionData[] = [];
+        for (const sessionId of set) {
+            const session = this.sessions.get(this.getSessionKey(identity, sessionId));
+            if (session) {
+                results.push(session);
+            }
+        }
+        return results;
+    }
+
+    async removeSession(identity: string, sessionId: string): Promise<void> {
+        const sessionKey = this.getSessionKey(identity, sessionId);
+        this.sessions.delete(sessionKey);
+
+        const set = this.identitySessions.get(identity);
+        if (set) {
+            set.delete(sessionId);
+            if (set.size === 0) {
+                this.identitySessions.delete(identity);
+            }
+        }
+    }
+
+    async getAllSessionIds(): Promise<string[]> {
+        return Array.from(this.sessions.values()).map(s => s.sessionId);
+    }
+
+    async clearAll(): Promise<void> {
+        this.sessions.clear();
+        this.identitySessions.clear();
+    }
+
+    async cleanupExpiredSessions(): Promise<void> {
+        // In-memory doesn't implement TTL automatically, 
+        // but we could check createdAt + TTL here if needed.
+        // For now, no-op.
+    }
+
+    async disconnect(): Promise<void> {
+        // No-op for memory
+    }
+}