@aexol/spectral 0.2.3 → 0.2.6

package/dist/mcp/logger.js

@@ -0,0 +1,130 @@
+/**
+ * Centralized logging for MCP UI operations.
+ * Provides structured, contextual logs with levels.
+ */
+const LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+const LEVEL_PREFIX = {
+    debug: "[MCP-UI:DEBUG]",
+    info: "[MCP-UI]",
+    warn: "[MCP-UI:WARN]",
+    error: "[MCP-UI:ERROR]",
+};
+class Logger {
+    minLevel = "info";
+    handlers = [];
+    defaultContext = {};
+    setLevel(level) {
+        this.minLevel = level;
+    }
+    setDefaultContext(context) {
+        this.defaultContext = context;
+    }
+    addHandler(handler) {
+        this.handlers.push(handler);
+    }
+    clearHandlers() {
+        this.handlers = [];
+    }
+    shouldLog(level) {
+        return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[this.minLevel];
+    }
+    emit(level, message, context, error) {
+        if (!this.shouldLog(level))
+            return;
+        const entry = {
+            level,
+            message,
+            context: { ...this.defaultContext, ...context },
+            error,
+            timestamp: new Date(),
+        };
+        // Default console output
+        const prefix = LEVEL_PREFIX[level];
+        const contextStr = formatContext(entry.context);
+        const fullMessage = contextStr ? `${prefix} ${message} ${contextStr}` : `${prefix} ${message}`;
+        if (level === "error") {
+            console.error(fullMessage, error ?? "");
+        }
+        else if (level === "warn") {
+            console.warn(fullMessage);
+        }
+        else if (level === "debug") {
+            console.debug(fullMessage);
+        }
+        else {
+            console.log(fullMessage);
+        }
+        // Custom handlers
+        for (const handler of this.handlers) {
+            try {
+                handler(entry);
+            }
+            catch {
+                // Ignore handler errors
+            }
+        }
+    }
+    debug(message, context) {
+        this.emit("debug", message, context);
+    }
+    info(message, context) {
+        this.emit("info", message, context);
+    }
+    warn(message, context) {
+        this.emit("warn", message, context);
+    }
+    error(message, error, context) {
+        this.emit("error", message, context, error);
+    }
+    /**
+     * Create a child logger with additional default context.
+     */
+    child(context) {
+        return new ChildLogger(this, context);
+    }
+}
+class ChildLogger {
+    parent;
+    context;
+    constructor(parent, context) {
+        this.parent = parent;
+        this.context = context;
+    }
+    debug(message, context) {
+        this.parent.debug(message, { ...this.context, ...context });
+    }
+    info(message, context) {
+        this.parent.info(message, { ...this.context, ...context });
+    }
+    warn(message, context) {
+        this.parent.warn(message, { ...this.context, ...context });
+    }
+    error(message, error, context) {
+        this.parent.error(message, error, { ...this.context, ...context });
+    }
+    child(context) {
+        return new ChildLogger(this.parent, { ...this.context, ...context });
+    }
+}
+function formatContext(context) {
+    if (!context || Object.keys(context).length === 0)
+        return "";
+    const parts = [];
+    for (const [key, value] of Object.entries(context)) {
+        if (value !== undefined && value !== null) {
+            parts.push(`${key}=${typeof value === "string" ? value : JSON.stringify(value)}`);
+        }
+    }
+    return parts.length > 0 ? `(${parts.join(", ")})` : "";
+}
+// Singleton instance
+export const logger = new Logger();
+// Enable debug mode via environment variable
+if (process.env.MCP_UI_DEBUG === "1" || process.env.MCP_UI_DEBUG === "true") {
+    logger.setLevel("debug");
+}

package/dist/mcp/mcp-auth-flow.js

@@ -0,0 +1,283 @@
+/**
+ * MCP Auth Flow
+ *
+ * High-level OAuth flow management using the MCP SDK's built-in auth functions.
+ */
+import { auth as runSdkAuth, UnauthorizedError, } from "@modelcontextprotocol/sdk/client/auth.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import open from "open";
+import { McpOAuthProvider } from "./mcp-oauth-provider.js";
+import { ensureCallbackServer, waitForCallback, cancelPendingCallback, stopCallbackServer, } from "./mcp-callback-server.js";
+import { getAuthForUrl, isTokenExpired, hasStoredTokens, clearAllCredentials, updateOAuthState, getOAuthState, clearOAuthState, } from "./mcp-auth.js";
+// Track pending transports for auth completion
+const pendingTransports = new Map();
+// Deduplicate concurrent authenticate() calls per server.
+const pendingAuthentications = new Map();
+/**
+ * Generate a cryptographically secure random state parameter.
+ */
+function generateState() {
+    return Array.from(crypto.getRandomValues(new Uint8Array(32)))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * Extract OAuth configuration from a ServerEntry.
+ */
+function extractOAuthConfig(definition) {
+    // If oauth is explicitly false, return empty config
+    if (definition.oauth === false) {
+        return {};
+    }
+    return {
+        grantType: definition.oauth?.grantType,
+        clientId: definition.oauth?.clientId,
+        clientSecret: definition.oauth?.clientSecret,
+        scope: definition.oauth?.scope,
+    };
+}
+/**
+ * Start OAuth authentication flow for a server.
+ * Returns the authorization URL when browser authorization is required.
+ */
+export async function startAuth(serverName, serverUrl, definition) {
+    const config = definition ? extractOAuthConfig(definition) : {};
+    if (config.grantType === "client_credentials") {
+        const authProvider = new McpOAuthProvider(serverName, serverUrl, config, {
+            onRedirect: async () => {
+                throw new Error("Browser redirect is not used for client_credentials flow");
+            },
+        });
+        const result = await runSdkAuth(authProvider, { serverUrl });
+        if (result !== "AUTHORIZED") {
+            throw new UnauthorizedError("Failed to authorize");
+        }
+        return { authorizationUrl: "" };
+    }
+    // Start the callback server.
+    // Pre-registered OAuth clients require an exact redirect URI, so enforce strict port binding.
+    await ensureCallbackServer({ strictPort: Boolean(config.clientId) });
+    const oauthState = generateState();
+    await updateOAuthState(serverName, oauthState);
+    let capturedUrl;
+    const authProvider = new McpOAuthProvider(serverName, serverUrl, config, {
+        onRedirect: async (url) => {
+            capturedUrl = url;
+        },
+    });
+    try {
+        const result = await runSdkAuth(authProvider, { serverUrl });
+        if (result === "AUTHORIZED") {
+            await clearOAuthState(serverName);
+            return { authorizationUrl: "" };
+        }
+        if (!capturedUrl) {
+            throw new UnauthorizedError("OAuth authorization URL was not provided");
+        }
+        pendingTransports.set(serverName, new StreamableHTTPClientTransport(new URL(serverUrl), { authProvider }));
+        return { authorizationUrl: capturedUrl.toString() };
+    }
+    catch (error) {
+        await clearOAuthState(serverName);
+        throw error;
+    }
+}
+/**
+ * Complete OAuth authentication with the authorization code.
+ */
+export async function completeAuth(serverName, authorizationCode) {
+    const transport = pendingTransports.get(serverName);
+    if (!transport) {
+        throw new Error(`No pending OAuth flow for server: ${serverName}`);
+    }
+    try {
+        // Complete the auth using the transport's finishAuth method
+        await transport.finishAuth(authorizationCode);
+        return "authenticated";
+    }
+    finally {
+        pendingTransports.delete(serverName);
+        await transport.close().catch(() => { });
+    }
+}
+/**
+ * Perform the complete OAuth authentication flow for a server.
+ *
+ * @param serverName - The name of the MCP server
+ * @param serverUrl - The URL of the MCP server
+ * @param definition - The server definition (optional)
+ * @returns The final auth status
+ */
+export async function authenticate(serverName, serverUrl, definition) {
+    const inFlight = pendingAuthentications.get(serverName);
+    if (inFlight) {
+        return inFlight;
+    }
+    const operation = (async () => {
+        // Start auth flow
+        const { authorizationUrl } = await startAuth(serverName, serverUrl, definition);
+        // If no auth URL needed, already authenticated
+        if (!authorizationUrl) {
+            return "authenticated";
+        }
+        // Get the state that was already generated and stored in startAuth()
+        const oauthState = await getOAuthState(serverName);
+        if (!oauthState) {
+            throw new Error("OAuth state not found - this should not happen");
+        }
+        // Register the callback BEFORE opening the browser
+        const callbackPromise = waitForCallback(oauthState);
+        try {
+            // Open browser
+            console.log(`MCP Auth: Opening browser for ${serverName}`);
+            try {
+                await open(authorizationUrl);
+            }
+            catch (error) {
+                console.warn(`MCP Auth: Failed to open browser for ${serverName}`, { error });
+                throw new Error(`Could not open browser. Please open this URL manually: ${authorizationUrl}`, { cause: error });
+            }
+            // Wait for callback
+            const code = await callbackPromise;
+            // Validate state
+            const storedState = await getOAuthState(serverName);
+            if (storedState !== oauthState) {
+                await clearOAuthState(serverName);
+                throw new Error("OAuth state mismatch - potential CSRF attack");
+            }
+            await clearOAuthState(serverName);
+            // Complete the auth
+            return await completeAuth(serverName, code);
+        }
+        catch (error) {
+            cancelPendingCallback(oauthState);
+            await clearOAuthState(serverName);
+            const pendingTransport = pendingTransports.get(serverName);
+            if (pendingTransport) {
+                pendingTransports.delete(serverName);
+                await pendingTransport.close().catch(() => { });
+            }
+            throw error;
+        }
+    })();
+    pendingAuthentications.set(serverName, operation);
+    try {
+        return await operation;
+    }
+    finally {
+        if (pendingAuthentications.get(serverName) === operation) {
+            pendingAuthentications.delete(serverName);
+        }
+    }
+}
+/**
+ * Get a valid access token for a server, refreshing if necessary.
+ *
+ * @param serverName - The name of the MCP server
+ * @param serverUrl - The URL of the MCP server
+ * @returns The valid tokens or null if not authenticated
+ */
+export async function getValidToken(serverName, serverUrl) {
+    // Check if we have valid tokens
+    const entry = await getAuthForUrl(serverName, serverUrl);
+    if (!entry?.tokens) {
+        return null;
+    }
+    // Check expiration
+    const expired = await isTokenExpired(serverName);
+    if (expired === false) {
+        return entry.tokens;
+    }
+    if (expired === true && entry.tokens.refreshToken) {
+        // Token is expired, try to refresh
+        console.log(`MCP Auth: Token expired for ${serverName}, attempting refresh`);
+        try {
+            // Create auth provider for token refresh
+            const authProvider = new McpOAuthProvider(serverName, serverUrl, {}, {
+                onRedirect: async () => { },
+            });
+            const clientInfo = await authProvider.clientInformation();
+            if (!clientInfo) {
+                console.log(`MCP Auth: No client info for refresh for ${serverName}`);
+                return null;
+            }
+            const result = await runSdkAuth(authProvider, { serverUrl });
+            if (result !== "AUTHORIZED") {
+                return null;
+            }
+            const refreshed = await getAuthForUrl(serverName, serverUrl);
+            return refreshed?.tokens ?? null;
+        }
+        catch (error) {
+            console.error(`MCP Auth: Token refresh failed for ${serverName}`, { error });
+            return null;
+        }
+    }
+    // No expiration info or no refresh token, assume valid
+    return entry.tokens;
+}
+/**
+ * Check the authentication status for a server.
+ *
+ * @param serverName - The name of the MCP server
+ * @returns The current auth status
+ */
+export async function getAuthStatus(serverName) {
+    const hasTokens = await hasStoredTokens(serverName);
+    if (!hasTokens)
+        return "not_authenticated";
+    const expired = await isTokenExpired(serverName);
+    return expired ? "expired" : "authenticated";
+}
+/**
+ * Remove all OAuth credentials for a server.
+ *
+ * @param serverName - The name of the MCP server
+ */
+export async function removeAuth(serverName) {
+    const oauthState = await getOAuthState(serverName);
+    if (oauthState) {
+        cancelPendingCallback(oauthState);
+    }
+    const pendingTransport = pendingTransports.get(serverName);
+    if (pendingTransport) {
+        pendingTransports.delete(serverName);
+        await pendingTransport.close().catch(() => { });
+    }
+    clearAllCredentials(serverName);
+    await clearOAuthState(serverName);
+    console.log(`MCP Auth: Removed credentials for ${serverName}`);
+}
+/**
+ * Check if OAuth is supported for a server configuration.
+ * OAuth is supported for HTTP servers unless explicitly disabled.
+ *
+ * @param definition - The server definition
+ * @returns True if OAuth is supported
+ */
+export function supportsOAuth(definition) {
+    // OAuth requires a URL
+    if (!definition.url)
+        return false;
+    // Explicitly disabled via auth: false or oauth: false
+    if (definition.auth === false)
+        return false;
+    if (definition.oauth === false)
+        return false;
+    // OAuth is enabled if auth is 'oauth' or not specified (auto-detect)
+    return definition.auth === "oauth" || definition.auth === undefined;
+}
+/**
+ * Initialize the OAuth system on startup.
+ * Starts the callback server if there are any OAuth servers configured.
+ */
+export async function initializeOAuth() {
+    await ensureCallbackServer();
+}
+/**
+ * Shutdown the OAuth system.
+ * Stops the callback server and cancels pending auths.
+ */
+export async function shutdownOAuth() {
+    await stopCallbackServer();
+}

package/dist/mcp/mcp-auth.js

@@ -0,0 +1,226 @@
+/**
+ * MCP Auth Storage Module
+ *
+ * Handles secure storage of OAuth credentials, tokens, client information,
+ * and PKCE state for MCP servers. Maintains backward compatibility with
+ * per-server directory structure.
+ *
+ * Token storage location: $MCP_OAUTH_DIR/<server>/tokens.json when set,
+ * otherwise <Pi agent dir>/mcp-oauth/<server>/tokens.json
+ */
+import { mkdirSync, readFileSync, writeFileSync, existsSync, rmSync } from 'fs';
+import { join } from 'path';
+import { getAgentPath } from './agent-dir.js';
+// Base directory for auth storage - can be overridden via env var for testing
+function getAuthBaseDir() {
+    const override = process.env.MCP_OAUTH_DIR?.trim();
+    return override ? override : getAgentPath('mcp-oauth');
+}
+/**
+ * Get the server-specific directory path.
+ */
+function getServerDir(serverName) {
+    return join(getAuthBaseDir(), serverName);
+}
+/**
+ * Get the tokens file path for a server.
+ */
+function getTokensFilePath(serverName) {
+    return join(getServerDir(serverName), 'tokens.json');
+}
+/**
+ * Ensure the server directory exists with secure permissions.
+ */
+function ensureServerDir(serverName) {
+    const dir = getServerDir(serverName);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+}
+/**
+ * Read the auth entry for a server from disk.
+ * Returns undefined if file doesn't exist.
+ */
+function readAuthEntry(serverName) {
+    try {
+        const filePath = getTokensFilePath(serverName);
+        if (!existsSync(filePath)) {
+            return undefined;
+        }
+        const data = readFileSync(filePath, 'utf-8');
+        return JSON.parse(data);
+    }
+    catch (error) {
+        console.error(`Failed to read auth entry for ${serverName}:`, error);
+        return undefined;
+    }
+}
+/**
+ * Write the auth entry for a server to disk with secure permissions.
+ */
+function writeAuthEntry(serverName, entry) {
+    ensureServerDir(serverName);
+    const filePath = getTokensFilePath(serverName);
+    writeFileSync(filePath, JSON.stringify(entry, null, 2), { mode: 0o600 });
+}
+/**
+ * Get auth entry for a server.
+ */
+export function getAuthEntry(serverName) {
+    return readAuthEntry(serverName);
+}
+/**
+ * Get auth entry and validate it's for the correct URL.
+ * Returns undefined if URL has changed (credentials are invalid).
+ */
+export function getAuthForUrl(serverName, serverUrl) {
+    const entry = getAuthEntry(serverName);
+    if (!entry)
+        return undefined;
+    // If no serverUrl is stored, this is from an old version - consider it invalid
+    if (!entry.serverUrl)
+        return undefined;
+    // If URL has changed, credentials are invalid
+    if (entry.serverUrl !== serverUrl)
+        return undefined;
+    return entry;
+}
+/**
+ * Save auth entry for a server.
+ */
+export function saveAuthEntry(serverName, entry, serverUrl) {
+    // Always update serverUrl if provided
+    if (serverUrl) {
+        entry.serverUrl = serverUrl;
+    }
+    writeAuthEntry(serverName, entry);
+}
+/**
+ * Remove auth entry for a server.
+ * Also removes the server directory if empty.
+ */
+export function removeAuthEntry(serverName) {
+    try {
+        const filePath = getTokensFilePath(serverName);
+        if (existsSync(filePath)) {
+            writeFileSync(filePath, '{}', { mode: 0o600 });
+        }
+        // Try to remove the directory
+        const dir = getServerDir(serverName);
+        if (existsSync(dir)) {
+            try {
+                rmSync(dir, { recursive: true });
+            }
+            catch {
+                // Directory may not be empty, ignore
+            }
+        }
+    }
+    catch (error) {
+        console.error(`Failed to remove auth entry for ${serverName}:`, error);
+    }
+}
+/**
+ * Update tokens for a server.
+ */
+export function updateTokens(serverName, tokens, serverUrl) {
+    const entry = getAuthEntry(serverName) ?? {};
+    entry.tokens = tokens;
+    saveAuthEntry(serverName, entry, serverUrl);
+}
+/**
+ * Update client info for a server.
+ */
+export function updateClientInfo(serverName, clientInfo, serverUrl) {
+    const entry = getAuthEntry(serverName) ?? {};
+    entry.clientInfo = clientInfo;
+    saveAuthEntry(serverName, entry, serverUrl);
+}
+/**
+ * Update code verifier for a server.
+ */
+export function updateCodeVerifier(serverName, codeVerifier) {
+    const entry = getAuthEntry(serverName) ?? {};
+    entry.codeVerifier = codeVerifier;
+    saveAuthEntry(serverName, entry);
+}
+/**
+ * Clear code verifier for a server.
+ */
+export function clearCodeVerifier(serverName) {
+    const entry = getAuthEntry(serverName);
+    if (entry) {
+        delete entry.codeVerifier;
+        saveAuthEntry(serverName, entry);
+    }
+}
+/**
+ * Update OAuth state for a server.
+ */
+export function updateOAuthState(serverName, state) {
+    const entry = getAuthEntry(serverName) ?? {};
+    entry.oauthState = state;
+    saveAuthEntry(serverName, entry);
+}
+/**
+ * Get OAuth state for a server.
+ */
+export function getOAuthState(serverName) {
+    const entry = getAuthEntry(serverName);
+    return entry?.oauthState;
+}
+/**
+ * Clear OAuth state for a server.
+ */
+export function clearOAuthState(serverName) {
+    const entry = getAuthEntry(serverName);
+    if (entry) {
+        delete entry.oauthState;
+        saveAuthEntry(serverName, entry);
+    }
+}
+/**
+ * Check if stored tokens are expired.
+ * Returns null if no tokens exist, false if no expiry or not expired, true if expired.
+ */
+export function isTokenExpired(serverName) {
+    const entry = getAuthEntry(serverName);
+    if (!entry?.tokens)
+        return null;
+    if (!entry.tokens.expiresAt)
+        return false;
+    return entry.tokens.expiresAt < Date.now() / 1000;
+}
+/**
+ * Check if a server has stored tokens.
+ */
+export function hasStoredTokens(serverName) {
+    const entry = getAuthEntry(serverName);
+    return !!entry?.tokens;
+}
+/**
+ * Clear all credentials for a server.
+ */
+export function clearAllCredentials(serverName) {
+    removeAuthEntry(serverName);
+}
+/**
+ * Clear only client info for a server.
+ */
+export function clearClientInfo(serverName) {
+    const entry = getAuthEntry(serverName);
+    if (entry) {
+        delete entry.clientInfo;
+        saveAuthEntry(serverName, entry);
+    }
+}
+/**
+ * Clear only tokens for a server.
+ */
+export function clearTokens(serverName) {
+    const entry = getAuthEntry(serverName);
+    if (entry) {
+        delete entry.tokens;
+        saveAuthEntry(serverName, entry);
+    }
+}