@1mcp/agent 0.10.3 → 0.11.0

package/build/server/auth/sessionManager.js

@@ -0,0 +1,376 @@
+import fs from 'fs';
+import path from 'path';
+import { randomUUID } from 'node:crypto';
+import logger from '../../logger/logger.js';
+import { AUTH_CONFIG, getGlobalConfigDir } from '../../constants.js';
+/**
+ * SessionManager handles file-based session storage with automatic cleanup.
+ *
+ * This class manages OAuth 2.1 sessions and authorization codes using
+ * the local filesystem. It provides automatic cleanup of expired sessions
+ * and supports configurable storage locations.
+ *
+ * Features:
+ * - File-based session storage with JSON format
+ * - Automatic cleanup of expired sessions every 5 minutes
+ * - Prefixed identifiers for easy debugging
+ * - Configurable storage directory
+ *
+ * @example
+ * ```typescript
+ * const sessionManager = new SessionManager('/custom/path');
+ * const sessionId = sessionManager.createSession('client-123', 'resource', 3600000);
+ * const session = sessionManager.getSession(sessionId);
+ * ```
+ */
+export class SessionManager {
+    sessionStoragePath;
+    cleanupInterval = null;
+    /**
+     * Creates a new SessionManager instance.
+     *
+     * Initializes the session storage directory and starts the automatic
+     * cleanup process for expired sessions.
+     *
+     * @param sessionStoragePath - Optional custom path for session storage
+     */
+    constructor(sessionStoragePath) {
+        this.sessionStoragePath = sessionStoragePath || path.join(getGlobalConfigDir(), AUTH_CONFIG.SESSION_STORAGE_DIR);
+        this.ensureSessionDirectory();
+        this.startCleanupInterval();
+    }
+    /**
+     * Ensures the session storage directory exists.
+     *
+     * Creates the directory structure if it doesn't exist, including
+     * parent directories as needed.
+     *
+     * @throws Error if directory creation fails
+     */
+    ensureSessionDirectory() {
+        try {
+            if (!fs.existsSync(this.sessionStoragePath)) {
+                fs.mkdirSync(this.sessionStoragePath, { recursive: true });
+                logger.info(`Created session storage directory: ${this.sessionStoragePath}`);
+            }
+        }
+        catch (error) {
+            logger.error(`Failed to create session directory: ${error}`);
+            throw error;
+        }
+    }
+    /**
+     * Gets the file path for a session ID.
+     *
+     * @param sessionId - The session identifier
+     * @returns Full file path for the session file
+     */
+    getSessionFilePath(sessionId) {
+        const filePath = path.resolve(this.sessionStoragePath, `${AUTH_CONFIG.SESSION_FILE_PREFIX}${sessionId}${AUTH_CONFIG.SESSION_FILE_EXTENSION}`);
+        if (!filePath.startsWith(this.sessionStoragePath)) {
+            throw new Error('Invalid session file path');
+        }
+        return filePath;
+    }
+    /**
+     * Gets the file path for an authorization code.
+     *
+     * @param code - The authorization code
+     * @returns Full file path for the auth code file
+     */
+    getAuthCodeFilePath(code) {
+        const filePath = path.resolve(this.sessionStoragePath, `auth_code_${code}${AUTH_CONFIG.SESSION_FILE_EXTENSION}`);
+        if (!filePath.startsWith(this.sessionStoragePath)) {
+            throw new Error('Invalid authorization code path');
+        }
+        return filePath;
+    }
+    /**
+     * Utility to validate session IDs and auth codes for safe characters (alphanumeric and dashes only).
+     * @param id - The session ID or auth code to validate
+     * @returns true if valid, false otherwise
+     */
+    isValidId(id) {
+        return /^[a-zA-Z0-9-]+$/.test(id);
+    }
+    /**
+     * Creates a new session with the specified parameters.
+     *
+     * Generates a unique session ID with prefix, stores the session data
+     * as a JSON file, and returns the session identifier.
+     *
+     * @param clientId - The client identifier
+     * @param resource - The resource this session can access
+     * @param ttlMs - Time-to-live in milliseconds
+     * @returns The generated session ID with prefix
+     * @throws Error if session creation fails
+     */
+    createSession(clientId, resource, ttlMs) {
+        const sessionId = AUTH_CONFIG.PREFIXES.SESSION_ID + randomUUID();
+        const sessionData = {
+            clientId,
+            resource,
+            expires: Date.now() + ttlMs,
+            createdAt: Date.now(),
+        };
+        try {
+            const filePath = this.getSessionFilePath(sessionId);
+            fs.writeFileSync(filePath, JSON.stringify(sessionData, null, 2));
+            logger.info(`Created session: ${sessionId} for client: ${clientId}`);
+            return sessionId;
+        }
+        catch (error) {
+            logger.error(`Failed to create session: ${error}`);
+            throw error;
+        }
+    }
+    /**
+     * Retrieves session data by session ID.
+     *
+     * Reads the session file and validates expiration. If the session
+     * is expired, it's automatically deleted and null is returned.
+     *
+     * @param sessionId - The session identifier to retrieve
+     * @returns Session data if valid and not expired, null otherwise
+     */
+    getSession(sessionId) {
+        if (!this.isValidId(sessionId)) {
+            logger.warn(`Rejected getSession with invalid sessionId: ${sessionId}`);
+            return null;
+        }
+        try {
+            const filePath = this.getSessionFilePath(sessionId);
+            if (!fs.existsSync(filePath)) {
+                return null;
+            }
+            const data = fs.readFileSync(filePath, 'utf8');
+            const sessionData = JSON.parse(data);
+            if (sessionData.expires < Date.now()) {
+                this.deleteSession(sessionId);
+                return null;
+            }
+            return sessionData;
+        }
+        catch (error) {
+            logger.error(`Failed to read session ${sessionId}: ${error}`);
+            return null;
+        }
+    }
+    /**
+     * Deletes a session by session ID.
+     *
+     * Removes the session file from the filesystem if it exists.
+     *
+     * @param sessionId - The session identifier to delete
+     * @returns True if session was deleted, false if it didn't exist
+     */
+    deleteSession(sessionId) {
+        if (!this.isValidId(sessionId)) {
+            logger.warn(`Rejected deleteSession with invalid sessionId: ${sessionId}`);
+            return false;
+        }
+        try {
+            const filePath = this.getSessionFilePath(sessionId);
+            if (fs.existsSync(filePath)) {
+                fs.unlinkSync(filePath);
+                logger.info(`Deleted session: ${sessionId}`);
+                return true;
+            }
+            return false;
+        }
+        catch (error) {
+            logger.error(`Failed to delete session ${sessionId}: ${error}`);
+            return false;
+        }
+    }
+    /**
+     * Creates a new authorization code for OAuth 2.1 flow.
+     *
+     * Generates a unique authorization code with prefix, stores the code data
+     * as a JSON file, and returns the code identifier.
+     *
+     * @param clientId - The client identifier
+     * @param redirectUri - The redirect URI for this code
+     * @param resource - The resource this code grants access to
+     * @param ttlMs - Time-to-live in milliseconds
+     * @returns The generated authorization code with prefix
+     * @throws Error if code creation fails
+     */
+    createAuthCode(clientId, redirectUri, resource, ttlMs) {
+        const code = AUTH_CONFIG.PREFIXES.AUTH_CODE + randomUUID();
+        const authCodeData = {
+            clientId,
+            redirectUri,
+            resource,
+            expires: Date.now() + ttlMs,
+            createdAt: Date.now(),
+        };
+        try {
+            const filePath = this.getAuthCodeFilePath(code);
+            fs.writeFileSync(filePath, JSON.stringify(authCodeData, null, 2));
+            logger.info(`Created auth code: ${code} for client: ${clientId}`);
+            return code;
+        }
+        catch (error) {
+            logger.error(`Failed to create auth code: ${error}`);
+            throw error;
+        }
+    }
+    /**
+     * Retrieves authorization code data by code.
+     *
+     * Reads the auth code file and validates expiration. If the code
+     * is expired, it's automatically deleted and null is returned.
+     *
+     * @param code - The authorization code to retrieve
+     * @returns Auth code data if valid and not expired, null otherwise
+     */
+    getAuthCode(code) {
+        if (!this.isValidId(code)) {
+            logger.warn(`Rejected getAuthCode with invalid code: ${code}`);
+            return null;
+        }
+        try {
+            const filePath = this.getAuthCodeFilePath(code);
+            if (!fs.existsSync(filePath)) {
+                return null;
+            }
+            const data = fs.readFileSync(filePath, 'utf8');
+            const authCodeData = JSON.parse(data);
+            if (authCodeData.expires < Date.now()) {
+                this.deleteAuthCode(code);
+                return null;
+            }
+            return authCodeData;
+        }
+        catch (error) {
+            logger.error(`Failed to read auth code ${code}: ${error}`);
+            return null;
+        }
+    }
+    /**
+     * Deletes an authorization code by code.
+     *
+     * Removes the auth code file from the filesystem if it exists.
+     *
+     * @param code - The authorization code to delete
+     * @returns True if code was deleted, false if it didn't exist
+     */
+    deleteAuthCode(code) {
+        if (!this.isValidId(code)) {
+            logger.warn(`Rejected deleteAuthCode with invalid code: ${code}`);
+            return false;
+        }
+        try {
+            const filePath = this.getAuthCodeFilePath(code);
+            if (fs.existsSync(filePath)) {
+                fs.unlinkSync(filePath);
+                logger.info(`Deleted auth code: ${code}`);
+                return true;
+            }
+            return false;
+        }
+        catch (error) {
+            logger.error(`Failed to delete auth code ${code}: ${error}`);
+            return false;
+        }
+    }
+    /**
+     * Starts the automatic cleanup interval for expired sessions.
+     *
+     * Runs cleanup every 5 minutes to remove expired sessions and
+     * authorization codes from the filesystem.
+     */
+    startCleanupInterval() {
+        // Clean up expired sessions every 5 minutes
+        this.cleanupInterval = setInterval(() => {
+            this.cleanupExpiredSessions();
+        }, 5 * 60 * 1000);
+    }
+    /**
+     * Cleans up expired sessions and authorization codes.
+     *
+     * Scans the session storage directory and removes all expired
+     * session and auth code files. Also handles corrupted files
+     * by removing them to prevent future errors.
+     */
+    cleanupExpiredSessions() {
+        try {
+            const files = fs.readdirSync(this.sessionStoragePath);
+            let cleanedCount = 0;
+            for (const file of files) {
+                if (file.endsWith(AUTH_CONFIG.SESSION_FILE_EXTENSION)) {
+                    const filePath = path.join(this.sessionStoragePath, file);
+                    try {
+                        const data = fs.readFileSync(filePath, 'utf8');
+                        const sessionData = JSON.parse(data);
+                        if (sessionData.expires < Date.now()) {
+                            fs.unlinkSync(filePath);
+                            cleanedCount++;
+                        }
+                    }
+                    catch (error) {
+                        logger.warn(`Failed to process session file ${file}: ${error}`);
+                        // Remove corrupted files
+                        try {
+                            fs.unlinkSync(filePath);
+                            cleanedCount++;
+                        }
+                        catch (unlinkError) {
+                            logger.error(`Failed to remove corrupted file ${file}: ${unlinkError}`);
+                        }
+                    }
+                }
+            }
+            if (cleanedCount > 0) {
+                logger.info(`Cleaned up ${cleanedCount} expired sessions`);
+            }
+        }
+        catch (error) {
+            logger.error(`Failed to cleanup expired sessions: ${error}`);
+        }
+    }
+    /**
+     * Performs graceful shutdown of the SessionManager.
+     *
+     * Stops the cleanup interval to prevent memory leaks and
+     * ensures proper resource cleanup.
+     */
+    shutdown() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+    }
+    /**
+     * Creates a new session with a custom ID (no prefix).
+     * Used for access tokens where the token ID is generated separately.
+     *
+     * @param tokenId - The raw UUID to use for the session (no prefix)
+     * @param clientId - The client identifier
+     * @param resource - The resource this session can access
+     * @param ttlMs - Time-to-live in milliseconds
+     * @returns The generated session ID with prefix
+     * @throws Error if session creation fails
+     */
+    createSessionWithId(tokenId, clientId, resource, ttlMs) {
+        const sessionId = AUTH_CONFIG.PREFIXES.SESSION_ID + tokenId;
+        const sessionData = {
+            clientId,
+            resource,
+            expires: Date.now() + ttlMs,
+            createdAt: Date.now(),
+        };
+        try {
+            const filePath = this.getSessionFilePath(sessionId);
+            fs.writeFileSync(filePath, JSON.stringify(sessionData, null, 2));
+            logger.info(`Created session: ${sessionId} for client: ${clientId}`);
+            return sessionId;
+        }
+        catch (error) {
+            logger.error(`Failed to create session: ${error}`);
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=sessionManager.js.map

package/build/server/auth/sessionManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionManager.js","sourceRoot":"","sources":["../../../src/server/auth/sessionManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,MAAM,MAAM,wBAAwB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAsCrE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,cAAc;IACjB,kBAAkB,CAAS;IAC3B,eAAe,GAA0C,IAAI,CAAC;IAEtE;;;;;;;OAOG;IACH,YAAY,kBAA2B;QACrC,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,IAAI,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,WAAW,CAAC,mBAAmB,CAAC,CAAC;QACjH,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAC9B,IAAI,CAAC,oBAAoB,EAAE,CAAC;IAC9B,CAAC;IAED;;;;;;;OAOG;IACK,sBAAsB;QAC5B,IAAI,CAAC;YACH,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC;gBAC5C,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC3D,MAAM,CAAC,IAAI,CAAC,sCAAsC,IAAI,CAAC,kBAAkB,EAAE,CAAC,CAAC;YAC/E,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,uCAAuC,KAAK,EAAE,CAAC,CAAC;YAC7D,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,kBAAkB,CAAC,SAAiB;QAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAC3B,IAAI,CAAC,kBAAkB,EACvB,GAAG,WAAW,CAAC,mBAAmB,GAAG,SAAS,GAAG,WAAW,CAAC,sBAAsB,EAAE,CACtF,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;QAC/C,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;;OAKG;IACK,mBAAmB,CAAC,IAAY;QACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,aAAa,IAAI,GAAG,WAAW,CAAC,sBAAsB,EAAE,CAAC,CAAC;QACjH,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACK,SAAS,CAAC,EAAU;QAC1B,OAAO,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IAED;;;;;;;;;;;OAWG;IACI,aAAa,CAAC,QAAgB,EAAE,QAAgB,EAAE,KAAa;QACpE,MAAM,SAAS,GAAG,WAAW,CAAC,QAAQ,CAAC,UAAU,GAAG,UAAU,EAAE,CAAC;QACjE,MAAM,WAAW,GAAgB;YAC/B,QAAQ;YACR,QAAQ;YACR,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;YAC3B,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC;YACpD,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YACjE,MAAM,CAAC,IAAI,CAAC,oBAAoB,SAAS,gBAAgB,QAAQ,EAAE,CAAC,CAAC;YACrE,OAAO,SAAS,CAAC;QACnB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,6BAA6B,KAAK,EAAE,CAAC,CAAC;YACnD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACI,UAAU,CAAC,SAAiB;QACjC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/B,MAAM,CAAC,IAAI,CAAC,+CAA+C,SAAS,EAAE,CAAC,CAAC;YACxE,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC;YACpD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC7B,OAAO,IAAI,CAAC;YACd,CAAC;YAED,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC/C,MAAM,WAAW,GAAgB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAElD,IAAI,WAAW,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;gBACrC,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;gBAC9B,OAAO,IAAI,CAAC;YACd,CAAC;YAED,OAAO,WAAW,CAAC;QACrB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,0BAA0B,SAAS,KAAK,KAAK,EAAE,CAAC,CAAC;YAC9D,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACI,aAAa,CAAC,SAAiB;QACpC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/B,MAAM,CAAC,IAAI,CAAC,kDAAkD,SAAS,EAAE,CAAC,CAAC;YAC3E,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC;YACpD,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC5B,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;gBACxB,MAAM,CAAC,IAAI,CAAC,oBAAoB,SAAS,EAAE,CAAC,CAAC;gBAC7C,OAAO,IAAI,CAAC;YACd,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,4BAA4B,SAAS,KAAK,KAAK,EAAE,CAAC,CAAC;YAChE,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;OAYG;IACI,cAAc,CAAC,QAAgB,EAAE,WAAmB,EAAE,QAAgB,EAAE,KAAa;QAC1F,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAC,SAAS,GAAG,UAAU,EAAE,CAAC;QAC3D,MAAM,YAAY,GAAiB;YACjC,QAAQ;YACR,WAAW;YACX,QAAQ;YACR,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;YAC3B,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;YAChD,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YAClE,MAAM,CAAC,IAAI,CAAC,sBAAsB,IAAI,gBAAgB,QAAQ,EAAE,CAAC,CAAC;YAClE,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,+BAA+B,KAAK,EAAE,CAAC,CAAC;YACrD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACI,WAAW,CAAC,IAAY;QAC7B,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,MAAM,CAAC,IAAI,CAAC,2CAA2C,IAAI,EAAE,CAAC,CAAC;YAC/D,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;YAChD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC7B,OAAO,IAAI,CAAC;YACd,CAAC;YAED,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC/C,MAAM,YAAY,GAAiB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAEpD,IAAI,YAAY,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;gBACtC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;gBAC1B,OAAO,IAAI,CAAC;YACd,CAAC;YAED,OAAO,YAAY,CAAC;QACtB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,4BAA4B,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC;YAC3D,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACI,cAAc,CAAC,IAAY;QAChC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,MAAM,CAAC,IAAI,CAAC,8CAA8C,IAAI,EAAE,CAAC,CAAC;YAClE,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;YAChD,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC5B,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;gBACxB,MAAM,CAAC,IAAI,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC;gBAC1C,OAAO,IAAI,CAAC;YACd,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,8BAA8B,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC;YAC7D,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,oBAAoB;QAC1B,4CAA4C;QAC5C,IAAI,CAAC,eAAe,GAAG,WAAW,CAChC,GAAG,EAAE;YACH,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAChC,CAAC,EACD,CAAC,GAAG,EAAE,GAAG,IAAI,CACd,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACK,sBAAsB;QAC5B,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;YACtD,IAAI,YAAY,GAAG,CAAC,CAAC;YAErB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,sBAAsB,CAAC,EAAE,CAAC;oBACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;oBAC1D,IAAI,CAAC;wBACH,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;wBAC/C,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;wBAErC,IAAI,WAAW,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;4BACrC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;4BACxB,YAAY,EAAE,CAAC;wBACjB,CAAC;oBACH,CAAC;oBAAC,OAAO,KAAK,EAAE,CAAC;wBACf,MAAM,CAAC,IAAI,CAAC,kCAAkC,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC;wBAChE,yBAAyB;wBACzB,IAAI,CAAC;4BACH,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;4BACxB,YAAY,EAAE,CAAC;wBACjB,CAAC;wBAAC,OAAO,WAAW,EAAE,CAAC;4BACrB,MAAM,CAAC,KAAK,CAAC,mCAAmC,IAAI,KAAK,WAAW,EAAE,CAAC,CAAC;wBAC1E,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;YAED,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;gBACrB,MAAM,CAAC,IAAI,CAAC,cAAc,YAAY,mBAAmB,CAAC,CAAC;YAC7D,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,uCAAuC,KAAK,EAAE,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACI,QAAQ;QACb,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,aAAa,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;YACpC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QAC9B,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACI,mBAAmB,CAAC,OAAe,EAAE,QAAgB,EAAE,QAAgB,EAAE,KAAa;QAC3F,MAAM,SAAS,GAAG,WAAW,CAAC,QAAQ,CAAC,UAAU,GAAG,OAAO,CAAC;QAC5D,MAAM,WAAW,GAAgB;YAC/B,QAAQ;YACR,QAAQ;YACR,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;YAC3B,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC;YACpD,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YACjE,MAAM,CAAC,IAAI,CAAC,oBAAoB,SAAS,gBAAgB,QAAQ,EAAE,CAAC,CAAC;YACrE,OAAO,SAAS,CAAC;QACnB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,6BAA6B,KAAK,EAAE,CAAC,CAAC;YACnD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

package/build/server/config/serverConfig.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Configuration interface for server-specific settings.
+ *
+ * Defines the structure for authentication and session management configuration
+ * that can be customized via CLI arguments or environment variables.
+ */
+export interface ServerConfig {
+    auth: {
+        enabled: boolean;
+        sessionTtlMinutes: number;
+        sessionStoragePath?: string;
+        oauthCodeTtlMs: number;
+        oauthTokenTtlMs: number;
+    };
+}
+/**
+ * ServerConfigManager manages server-specific configuration settings.
+ *
+ * This singleton class handles authentication and session configuration
+ * that differs from the main MCP server configuration. It provides
+ * centralized access to server settings with default values and
+ * runtime configuration updates.
+ *
+ * @example
+ * ```typescript
+ * const configManager = ServerConfigManager.getInstance();
+ * configManager.updateConfig({
+ *   auth: { enabled: true, sessionTtlMinutes: 60 }
+ * });
+ * ```
+ */
+export declare class ServerConfigManager {
+    private static instance;
+    private config;
+    /**
+     * Private constructor to enforce singleton pattern.
+     *
+     * Initializes the configuration with default values from constants.
+     * Should not be called directly - use getInstance() instead.
+     */
+    private constructor();
+    /**
+     * Gets the singleton instance of ServerConfigManager.
+     *
+     * Creates a new instance if one doesn't exist, otherwise returns
+     * the existing instance to ensure configuration consistency.
+     *
+     * @returns The singleton ServerConfigManager instance
+     */
+    static getInstance(): ServerConfigManager;
+    /**
+     * Updates the server configuration with new values.
+     *
+     * Merges the provided updates with existing configuration, allowing
+     * partial updates while preserving other settings.
+     *
+     * @param updates - Partial configuration object with new values
+     */
+    updateConfig(updates: Partial<ServerConfig>): void;
+    /**
+     * Gets a copy of the current server configuration.
+     *
+     * Returns a deep copy to prevent external modification of the
+     * internal configuration state.
+     *
+     * @returns Current server configuration
+     */
+    getConfig(): ServerConfig;
+    /**
+     * Checks if authentication is currently enabled.
+     *
+     * @returns True if OAuth 2.1 authentication is enabled, false otherwise
+     */
+    isAuthEnabled(): boolean;
+    /**
+     * Gets the session time-to-live in minutes.
+     *
+     * @returns Session TTL in minutes
+     */
+    getSessionTtlMinutes(): number;
+    /**
+     * Gets the custom session storage path if configured.
+     *
+     * @returns Custom session storage path or undefined if using default
+     */
+    getSessionStoragePath(): string | undefined;
+    /**
+     * Gets the OAuth authorization code time-to-live in milliseconds.
+     *
+     * @returns OAuth code TTL in milliseconds
+     */
+    getOAuthCodeTtlMs(): number;
+    /**
+     * Gets the OAuth access token time-to-live in milliseconds.
+     *
+     * @returns OAuth token TTL in milliseconds
+     */
+    getOAuthTokenTtlMs(): number;
+}
+//# sourceMappingURL=serverConfig.d.ts.map

package/build/server/config/serverConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverConfig.d.ts","sourceRoot":"","sources":["../../../src/server/config/serverConfig.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE;QACJ,OAAO,EAAE,OAAO,CAAC;QACjB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,cAAc,EAAE,MAAM,CAAC;QACvB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAsB;IAC7C,OAAO,CAAC,MAAM,CAAe;IAE7B;;;;;OAKG;IACH,OAAO;IAWP;;;;;;;OAOG;WACW,WAAW,IAAI,mBAAmB;IAOhD;;;;;;;OAOG;IACI,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAOzD;;;;;;;OAOG;IACI,SAAS,IAAI,YAAY;IAIhC;;;;OAIG;IACI,aAAa,IAAI,OAAO;IAI/B;;;;OAIG;IACI,oBAAoB,IAAI,MAAM;IAIrC;;;;OAIG;IACI,qBAAqB,IAAI,MAAM,GAAG,SAAS;IAIlD;;;;OAIG;IACI,iBAAiB,IAAI,MAAM;IAIlC;;;;OAIG;IACI,kBAAkB,IAAI,MAAM;CAGpC"}

package/build/server/config/serverConfig.js

@@ -0,0 +1,117 @@
+import { AUTH_CONFIG } from '../../constants.js';
+/**
+ * ServerConfigManager manages server-specific configuration settings.
+ *
+ * This singleton class handles authentication and session configuration
+ * that differs from the main MCP server configuration. It provides
+ * centralized access to server settings with default values and
+ * runtime configuration updates.
+ *
+ * @example
+ * ```typescript
+ * const configManager = ServerConfigManager.getInstance();
+ * configManager.updateConfig({
+ *   auth: { enabled: true, sessionTtlMinutes: 60 }
+ * });
+ * ```
+ */
+export class ServerConfigManager {
+    static instance;
+    config;
+    /**
+     * Private constructor to enforce singleton pattern.
+     *
+     * Initializes the configuration with default values from constants.
+     * Should not be called directly - use getInstance() instead.
+     */
+    constructor() {
+        this.config = {
+            auth: {
+                enabled: AUTH_CONFIG.DEFAULT_ENABLED,
+                sessionTtlMinutes: AUTH_CONFIG.DEFAULT_SESSION_TTL_MINUTES,
+                oauthCodeTtlMs: AUTH_CONFIG.DEFAULT_OAUTH_CODE_TTL_MS,
+                oauthTokenTtlMs: AUTH_CONFIG.DEFAULT_OAUTH_TOKEN_TTL_MS,
+            },
+        };
+    }
+    /**
+     * Gets the singleton instance of ServerConfigManager.
+     *
+     * Creates a new instance if one doesn't exist, otherwise returns
+     * the existing instance to ensure configuration consistency.
+     *
+     * @returns The singleton ServerConfigManager instance
+     */
+    static getInstance() {
+        if (!ServerConfigManager.instance) {
+            ServerConfigManager.instance = new ServerConfigManager();
+        }
+        return ServerConfigManager.instance;
+    }
+    /**
+     * Updates the server configuration with new values.
+     *
+     * Merges the provided updates with existing configuration, allowing
+     * partial updates while preserving other settings.
+     *
+     * @param updates - Partial configuration object with new values
+     */
+    updateConfig(updates) {
+        this.config = { ...this.config, ...updates };
+        if (updates.auth) {
+            this.config.auth = { ...this.config.auth, ...updates.auth };
+        }
+    }
+    /**
+     * Gets a copy of the current server configuration.
+     *
+     * Returns a deep copy to prevent external modification of the
+     * internal configuration state.
+     *
+     * @returns Current server configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Checks if authentication is currently enabled.
+     *
+     * @returns True if OAuth 2.1 authentication is enabled, false otherwise
+     */
+    isAuthEnabled() {
+        return this.config.auth.enabled;
+    }
+    /**
+     * Gets the session time-to-live in minutes.
+     *
+     * @returns Session TTL in minutes
+     */
+    getSessionTtlMinutes() {
+        return this.config.auth.sessionTtlMinutes;
+    }
+    /**
+     * Gets the custom session storage path if configured.
+     *
+     * @returns Custom session storage path or undefined if using default
+     */
+    getSessionStoragePath() {
+        return this.config.auth.sessionStoragePath;
+    }
+    /**
+     * Gets the OAuth authorization code time-to-live in milliseconds.
+     *
+     * @returns OAuth code TTL in milliseconds
+     */
+    getOAuthCodeTtlMs() {
+        return this.config.auth.oauthCodeTtlMs;
+    }
+    /**
+     * Gets the OAuth access token time-to-live in milliseconds.
+     *
+     * @returns OAuth token TTL in milliseconds
+     */
+    getOAuthTokenTtlMs() {
+        return this.config.auth.oauthTokenTtlMs;
+    }
+}
+//# sourceMappingURL=serverConfig.js.map

package/build/server/config/serverConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverConfig.js","sourceRoot":"","sources":["../../../src/server/config/serverConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAkBjD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,mBAAmB;IACtB,MAAM,CAAC,QAAQ,CAAsB;IACrC,MAAM,CAAe;IAE7B;;;;;OAKG;IACH;QACE,IAAI,CAAC,MAAM,GAAG;YACZ,IAAI,EAAE;gBACJ,OAAO,EAAE,WAAW,CAAC,eAAe;gBACpC,iBAAiB,EAAE,WAAW,CAAC,2BAA2B;gBAC1D,cAAc,EAAE,WAAW,CAAC,yBAAyB;gBACrD,eAAe,EAAE,WAAW,CAAC,0BAA0B;aACxD;SACF,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACI,MAAM,CAAC,WAAW;QACvB,IAAI,CAAC,mBAAmB,CAAC,QAAQ,EAAE,CAAC;YAClC,mBAAmB,CAAC,QAAQ,GAAG,IAAI,mBAAmB,EAAE,CAAC;QAC3D,CAAC;QACD,OAAO,mBAAmB,CAAC,QAAQ,CAAC;IACtC,CAAC;IAED;;;;;;;OAOG;IACI,YAAY,CAAC,OAA8B;QAChD,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC;QAC7C,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YACjB,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAC9D,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACI,SAAS;QACd,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACI,aAAa;QAClB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACI,oBAAoB;QACzB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC;IAC5C,CAAC;IAED;;;;OAIG;IACI,qBAAqB;QAC1B,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC;IAC7C,CAAC;IAED;;;;OAIG;IACI,iBAAiB;QACtB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC;IACzC,CAAC;IAED;;;;OAIG;IACI,kBAAkB;QACvB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC;IAC1C,CAAC;CACF"}

package/build/server/expressServer.d.ts

@@ -1,11 +1,69 @@
 import { ServerManager } from '../serverManager.js';
+/**
+ * ExpressServer orchestrates the HTTP/SSE transport layer for the MCP server.
+ *
+ * This class manages the Express application, authentication, and route setup.
+ * It provides both HTTP and SSE transport options with optional OAuth 2.1 authentication.
+ *
+ * @example
+ * ```typescript
+ * const serverManager = await setupServer();
+ * const expressServer = new ExpressServer(serverManager);
+ * expressServer.start(3050, 'localhost');
+ * ```
+ */
 export declare class ExpressServer {
     private app;
     private serverManager;
+    private authManager;
+    private configManager;
+    /**
+     * Creates a new ExpressServer instance.
+     *
+     * Initializes the Express application, sets up middleware, authentication,
+     * and configures all routes for MCP transport and OAuth endpoints.
+     *
+     * @param serverManager - The server manager instance for handling MCP operations
+     */
     constructor(serverManager: ServerManager);
+    /**
+     * Sets up Express middleware including CORS, body parsing, and error handling.
+     *
+     * Configures the basic middleware stack required for the MCP server:
+     * - CORS for cross-origin requests
+     * - JSON body parsing
+     * - Global error handling
+     */
     private setupMiddleware;
-    private setupStreamableHttpRoutes;
-    private setupSseRoutes;
+    /**
+     * Sets up all application routes including OAuth and MCP transport endpoints.
+     *
+     * Configures the following route groups:
+     * - OAuth 2.1 endpoints (always available, auth can be disabled)
+     * - Streamable HTTP transport routes with authentication middleware
+     * - SSE transport routes with authentication middleware
+     *
+     * Logs the authentication status for debugging purposes.
+     */
+    private setupRoutes;
+    /**
+     * Starts the Express server on the specified port and host.
+     *
+     * Binds the Express application to the network interface and logs
+     * the server status including authentication configuration.
+     *
+     * @param port - The port number to listen on
+     * @param host - The host address to bind to
+     */
     start(port: number, host: string): void;
+    /**
+     * Performs graceful shutdown of the Express server.
+     *
+     * Cleans up resources including:
+     * - Authentication manager shutdown
+     * - Session cleanup
+     * - Timer cleanup
+     */
+    shutdown(): void;
 }
 //# sourceMappingURL=expressServer.d.ts.map