@nestr/mcp 0.1.71 → 0.1.73

package/build/http.js

@@ -33,7 +33,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { createServer } from "./server.js";
 import { toolDefinitions } from "./tools/index.js";
-import { NestrClient, NestrApiError } from "./api/client.js";
+import { NestrClient, NestrApiError, tokenFingerprint } from "./api/client.js";
 import { getProtectedResourceMetadata, getAuthorizationServerMetadata, getOAuthConfig, } from "./oauth/config.js";
 import { createAuthorizationRequest, getPendingAuth, exchangeCodeForTokens, storeOAuthSession, verifyPKCE, getOAuthSession, } from "./oauth/flow.js";
 import { initStore, getStore, } from "./oauth/store.js";
@@ -46,6 +46,8 @@ import path from "path";
 import fs from "fs";
 import { fileURLToPath } from "url";
 import { VERSION } from "./version.js";
+import { runWithContext, cidTag } from "./util/request-context.js";
+import { tryDecodeJwtAge } from "./util/diagnose.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const PORT = process.env.PORT || 3000;
@@ -322,6 +324,10 @@ app.get("/oauth/authorize", oauthLimiter, async (req, res) => {
     const codeChallenge = req.query.code_challenge;
     const codeChallengeMethod = req.query.code_challenge_method;
     const clientConsumer = req.query.client_consumer;
+    // MCP `clientInfo.version` forwarded from the initialize handshake. Slashme-online
+    // persists it on the issued token row (see PR #1392) for triage / outdated-install
+    // detection. We just plumb the URL param through.
+    const clientVersion = req.query.client_version;
     // GA4 analytics: use provided client_id or generate new one for tracking
     const gaClientId = req.query._ga_client_id ||
         (analytics.isEnabled() ? analytics.generateClientId() : undefined);
@@ -391,6 +397,7 @@ app.get("/oauth/authorize", oauthLimiter, async (req, res) => {
                 codeChallenge,
                 codeChallengeMethod: codeChallengeMethod || "S256",
                 clientConsumer: effectiveClientConsumer,
+                clientVersion,
                 gaClientId,
             });
             // Override the redirect_uri in the auth URL to use OUR callback
@@ -610,7 +617,7 @@ app.get("/oauth/callback", async (req, res) => {
 app.post("/oauth/device", oauthLimiter, express.urlencoded({ extended: true }), async (req, res) => {
     const config = getOAuthConfig();
     try {
-        const { client_id, scope, client_consumer } = req.body;
+        const { client_id, scope, client_consumer, client_version } = req.body;
         // Require client_id
         if (!client_id) {
             res.status(400).json({
@@ -653,7 +660,11 @@ app.post("/oauth/device", oauthLimiter, express.urlencoded({ extended: true }),
         if (effectiveClientConsumer) {
             body.client_consumer = effectiveClientConsumer;
         }
-        console.log(`OAuth Device: Requesting device code from Nestr${effectiveClientConsumer ? ` (consumer: ${effectiveClientConsumer})` : ""}`);
+        // Pass client_version (MCP `clientInfo.version`) for triage / outdated-install detection.
+        if (client_version) {
+            body.client_version = client_version;
+        }
+        console.log(`OAuth Device: Requesting device code from Nestr${effectiveClientConsumer ? ` (consumer: ${effectiveClientConsumer})` : ""}${client_version ? ` v${client_version}` : ""}`);
         const response = await fetch(config.deviceAuthorizationEndpoint, {
             method: "POST",
             headers: {
@@ -691,7 +702,7 @@ app.post("/oauth/token", tokenLimiter, express.urlencoded({ extended: true }), a
     const config = getOAuthConfig();
     try {
         // Get form body params
-        const { grant_type, code, redirect_uri, refresh_token, client_id, client_secret, code_verifier, client_consumer, } = req.body;
+        const { grant_type, code, redirect_uri, refresh_token, client_id, client_secret, code_verifier, client_consumer, client_version, } = req.body;
         if (grant_type === "authorization_code") {
             if (!code) {
                 res.status(400).json({
@@ -763,6 +774,12 @@ app.post("/oauth/token", tokenLimiter, express.urlencoded({ extended: true }), a
             if (client_consumer) {
                 body.client_consumer = client_consumer;
             }
+            // Pass client_version (MCP `clientInfo.version`) — slashme-online persists
+            // it on the token row alongside the consumer for triage / outdated-install
+            // detection. Ignored upstream until that PR lands.
+            if (client_version) {
+                body.client_version = client_version;
+            }
             const response = await fetch(config.tokenEndpoint, {
                 method: "POST",
                 headers: {
@@ -826,6 +843,9 @@ app.post("/oauth/token", tokenLimiter, express.urlencoded({ extended: true }), a
             if (client_consumer) {
                 body.client_consumer = client_consumer;
             }
+            if (client_version) {
+                body.client_version = client_version;
+            }
             console.log(`OAuth Token: Polling device code at Nestr${client_consumer ? ` (consumer: ${client_consumer})` : ""}`);
             const response = await fetch(config.tokenEndpoint, {
                 method: "POST",
@@ -851,6 +871,10 @@ app.post("/oauth/token", tokenLimiter, express.urlencoded({ extended: true }), a
         });
     }
 });
+// How long a successful upstream auth check is good for. 60s is enough to
+// amortize the probe across a normal tool burst without letting a freshly
+// revoked token slip past for too long.
+const AUTH_VERIFY_TTL_MS = 60 * 1000;
 export const sessions = {};
 let shuttingDown = false;
 let inFlightRequests = 0;
@@ -994,29 +1018,43 @@ function cacheIdentity(token, userId, userName) {
 function buildMcpSession(opts) {
     const sessionStartTime = Date.now();
     let sessionRef;
+    const flow = opts.hasStoredOAuthSession ? "A" : opts.isApiKey ? "unknown" : "B";
     const client = new NestrClient({
         apiKey: opts.authToken,
         baseUrl: process.env.NESTR_API_BASE,
         mcpClient: opts.mcpClient,
-        // tokenProvider enables server-side token refresh for stored sessions (browser flow).
+        flow,
+        // tokenProvider enables server-side token refresh for stored sessions (Flow A).
         // In the standard MCP OAuth flow there's no stored session — the client manages refresh.
         // When tokenProvider is undefined, NestrClient lets 401 propagate to the client.
         tokenProvider: opts.hasStoredOAuthSession ? async () => {
             const session = await getOAuthSession(opts.authToken);
             if (!session) {
-                // Stored session expired and refresh failed — surface a 401 to the
-                // client without ripping the MCP session out from under the protocol.
-                // The HTTP-level pre-check in the POST handler will normally catch
-                // this first; this is the in-flight fallback.
+                // Stored session expired and refresh failed — surface a typed
+                // AUTH_REFRESH_FAILED so the client can branch on it. The HTTP-level
+                // pre-check in the POST handler normally catches this first; this is
+                // the in-flight fallback.
                 const sid = sessionRef?.transport?.sessionId;
-                console.log(`OAuth session expired mid-session (MCP session: ${sid ?? "unknown"}). Returning 401 to client.`);
+                console.log(`${cidTag()}OAuth session expired mid-session (MCP session: ${sid ?? "unknown"}). Returning AUTH_REFRESH_FAILED to client.`);
                 throw new NestrApiError("OAuth session expired", 401, "/", {
-                    code: "AUTH_FAILED",
-                    hint: "Your OAuth session has expired or the server was restarted. Reconnect to the MCP server to re-authenticate.",
+                    code: "AUTH_REFRESH_FAILED",
+                    flow: "A",
+                    hint: "Server-side refresh failed (session expired or server was restarted). User must reconnect Nestr to re-authenticate.",
                 });
             }
             return session.accessToken;
         } : undefined,
+        onUpstreamAuthFailure: () => {
+            if (sessionRef) {
+                sessionRef.authInvalidated = true;
+                sessionRef.lastUpstream401At = Date.now();
+            }
+        },
+        onRefreshAttempt: (result) => {
+            if (sessionRef) {
+                sessionRef.lastRefreshAttempt = result;
+            }
+        },
     });
     const server = createServer({
         client,
@@ -1040,18 +1078,33 @@ function buildMcpSession(opts) {
                 console.error("[Analytics] Tool call tracking error:", e);
             }
         },
+        getDiagnose: () => ({
+            flow: opts.hasStoredOAuthSession ? "A" : opts.isApiKey ? "unknown" : "B",
+            tokenPresented: !!opts.authToken,
+            tokenFingerprint: tokenFingerprint(opts.authToken),
+            tokenAge: tryDecodeJwtAge(opts.authToken),
+            lastUpstream401At: sessionRef?.lastUpstream401At,
+            lastRefreshAttempt: sessionRef?.lastRefreshAttempt,
+            sessionCorrelationId: sessionRef?.sessionCorrelationId,
+            hasStoredOAuthSession: opts.hasStoredOAuthSession,
+            isApiKey: opts.isApiKey,
+            mcpClient: opts.mcpClient,
+            mcpClientVersion: opts.mcpClientVersion,
+            userId: opts.userId,
+        }),
     });
     const transport = new StreamableHTTPServerTransport({
         sessionIdGenerator: () => opts.rehydrateFor ?? randomUUID(),
         enableJsonResponse: opts.wantsJsonOnly,
         onsessioninitialized: (newSessionId) => {
             // Only fires for fresh sessions — rehydrated transports skip the handshake.
-            console.log(`Session initialized: ${newSessionId}${opts.mcpClient ? ` (client: ${opts.mcpClient})` : ""}`);
+            console.log(`${cidTag()}Session initialized: ${newSessionId}${opts.mcpClient ? ` (client: ${opts.mcpClient}${opts.mcpClientVersion ? ` v${opts.mcpClientVersion}` : ""})` : ""}`);
             const sessionData = {
                 transport,
                 server,
                 authToken: opts.authToken,
                 mcpClient: opts.mcpClient,
+                mcpClientVersion: opts.mcpClientVersion,
                 isApiKey: opts.isApiKey,
                 wantsJsonOnly: opts.wantsJsonOnly,
                 hasStoredOAuthSession: opts.hasStoredOAuthSession,
@@ -1062,6 +1115,7 @@ function buildMcpSession(opts) {
                 sessionStartTime,
                 lastActivityAt: Date.now(),
                 lastPersistedAt: Date.now(),
+                sessionCorrelationId: randomUUID(),
             };
             sessions[newSessionId] = sessionData;
             sessionRef = sessionData;
@@ -1069,6 +1123,7 @@ function buildMcpSession(opts) {
             getStore().storeMcpSession(newSessionId, {
                 authToken: opts.authToken,
                 mcpClient: opts.mcpClient,
+                mcpClientVersion: opts.mcpClientVersion,
                 userId: opts.userId,
                 userName: opts.userName,
                 isApiKey: opts.isApiKey,
@@ -1131,6 +1186,7 @@ function buildMcpSession(opts) {
             server,
             authToken: opts.authToken,
             mcpClient: opts.mcpClient,
+            mcpClientVersion: opts.mcpClientVersion,
             isApiKey: opts.isApiKey,
             wantsJsonOnly: opts.wantsJsonOnly,
             hasStoredOAuthSession: opts.hasStoredOAuthSession,
@@ -1141,10 +1197,11 @@ function buildMcpSession(opts) {
             sessionStartTime,
             lastActivityAt: Date.now(),
             lastPersistedAt: Date.now(),
+            sessionCorrelationId: randomUUID(),
         };
         sessions[opts.rehydrateFor] = sessionData;
         sessionRef = sessionData;
-        console.log(`[Rehydrate] Rebuilt session ${opts.rehydrateFor} (client: ${opts.mcpClient ?? "unknown"})`);
+        console.log(`${cidTag()}[Rehydrate] Rebuilt session ${opts.rehydrateFor} (client: ${opts.mcpClient ?? "unknown"}${opts.mcpClientVersion ? ` v${opts.mcpClientVersion}` : ""})`);
         return sessionData;
     }
     // Fresh session: caller still needs to attach via server.connect(transport)
@@ -1154,6 +1211,7 @@ function buildMcpSession(opts) {
         server,
         authToken: opts.authToken,
         mcpClient: opts.mcpClient,
+        mcpClientVersion: opts.mcpClientVersion,
         isApiKey: opts.isApiKey,
         wantsJsonOnly: opts.wantsJsonOnly,
         hasStoredOAuthSession: opts.hasStoredOAuthSession,
@@ -1202,6 +1260,7 @@ async function rehydrateSession(sessionId, authToken) {
         authToken: stored.authToken,
         isApiKey: stored.isApiKey,
         mcpClient: stored.mcpClient,
+        mcpClientVersion: stored.mcpClientVersion,
         userId: stored.userId,
         userName: stored.userName,
         wantsJsonOnly: stored.wantsJsonOnly,
@@ -1244,13 +1303,144 @@ export function getAuthToken(req) {
     return null;
 }
 /**
- * Build WWW-Authenticate header for 401 responses
- * Directs MCP clients to the OAuth protected resource metadata
+ * Build WWW-Authenticate header for 401 responses (RFC 6750 + RFC 9728).
+ *
+ * `resource_metadata` points the MCP client at our metadata endpoint so it can
+ * discover the authorization server. `error` / `error_description` follow
+ * RFC 6750 §3 so a SDK that surfaces the header can display a useful reason.
  */
-function buildWwwAuthenticateHeader(req) {
+function buildWwwAuthenticateHeader(req, options = {}) {
     const baseUrl = getServerBaseUrl(req);
     const metadataUrl = `${baseUrl}/.well-known/oauth-protected-resource`;
-    return `Bearer resource_metadata="${metadataUrl}"`;
+    const parts = [`resource_metadata="${metadataUrl}"`];
+    if (options.error) {
+        parts.push(`error="${options.error}"`);
+    }
+    if (options.errorDescription) {
+        // Keep description ASCII-safe; strip quotes to avoid breaking the header.
+        parts.push(`error_description="${options.errorDescription.replace(/"/g, "'")}"`);
+    }
+    return `Bearer ${parts.join(", ")}`;
+}
+function isToolCallRequest(body) {
+    return !!body && typeof body === "object" && body.method === "tools/call";
+}
+/**
+ * Pre-flight upstream auth check.
+ *
+ * Goal: when the bearer is dead, we want to respond with HTTP 401 +
+ * WWW-Authenticate (which triggers the MCP SDK's auto-refresh) instead of a
+ * `tools/call` JSON-RPC result with `isError: true` (which is invisible to
+ * the SDK's auth machinery — that was the original Cowork bug).
+ *
+ * Strategy:
+ *   1. If `session.authInvalidated` is set, a previous in-flight call already
+ *      saw a 401. Return HTTP 401 immediately for any method (tools/call,
+ *      tools/list, ping…) so the client knows to re-auth. Clear the flag so a
+ *      subsequent request (after the client refreshes) can re-verify.
+ *   2. Non-tool methods (tools/list, ping, resources/*) don't talk to Nestr.
+ *      Skip the upstream probe entirely — the next tools/call will catch any
+ *      expired session.
+ *   3. For tools/call, probe Nestr with a cheap, idempotent call:
+ *        - Flow A (stored OAuth session): refresh-or-return via getOAuthSession.
+ *        - Flow B (Bearer, no stored session): GET /users/me, cached 60s.
+ *        - API key: GET /workspaces?limit=1, cached 60s.
+ *      A 200 → cache verified-at-now (Flow B/API key). A 401 → return HTTP 401.
+ *
+ * Skipped for `nestr_diagnose` since that tool's whole purpose is to be
+ * callable without auth.
+ */
+async function preflightAuthCheck(req, res, session, toolName, isToolCall) {
+    if (toolName === "nestr_diagnose")
+        return { blocked: false };
+    const replyWith401 = (errorDescription) => {
+        res.status(401);
+        res.setHeader("WWW-Authenticate", buildWwwAuthenticateHeader(req, { error: "invalid_token", errorDescription }));
+        res.json({
+            jsonrpc: "2.0",
+            error: {
+                code: -32001,
+                message: "Authentication required. Token rejected by Nestr.",
+                data: {
+                    flow: session.hasStoredOAuthSession ? "A" : session.isApiKey ? "unknown" : "B",
+                    hint: session.hasStoredOAuthSession
+                        ? "Server-side refresh failed. Reconnect Nestr to re-authenticate."
+                        : session.isApiKey
+                            ? "API key was rejected. Regenerate the workspace API key."
+                            : "Bearer was rejected by Nestr. Refresh via /oauth/token, or run a fresh OAuth flow if refresh also fails.",
+                    correlationId: session.sessionCorrelationId,
+                },
+            },
+            id: req.body?.id ?? null,
+        });
+    };
+    // Always-on: a previous tool call on this session saw upstream 401.
+    // Whatever method is being called now, fail fast so the client re-auths.
+    // This stays unconditional (cheap — just a flag check) so an in-flight 401
+    // on a tool call surfaces as transport 401 on whatever the *next* request
+    // happens to be, even if it's a `tools/list` or `ping`.
+    if (session.authInvalidated) {
+        console.log(`${cidTag()}[Preflight] session previously saw upstream 401 → returning HTTP 401`);
+        session.authInvalidated = false; // one-shot: clear so a refreshed retry can re-verify
+        session.lastAuthVerifiedAt = undefined;
+        replyWith401("Bearer rejected by Nestr on a prior request");
+        return { blocked: true };
+    }
+    // Non-tool calls (`tools/list`, `ping`, `resources/*`, etc.) don't talk to
+    // Nestr, so they don't need an upstream auth check. Skip out before any
+    // Redis read. The next `tools/call` will catch any expired session.
+    if (!isToolCall)
+        return { blocked: false };
+    // Flow A: refresh-or-return without an extra Nestr round-trip.
+    // getOAuthSession refreshes if the access token is near expiry; if the
+    // refresh fails the session is wiped and we surface the 401.
+    if (session.hasStoredOAuthSession) {
+        try {
+            const oauthSession = await getOAuthSession(session.authToken);
+            if (!oauthSession) {
+                replyWith401("Stored OAuth session has expired and could not be refreshed");
+                return { blocked: true };
+            }
+        }
+        catch (e) {
+            console.error(`${cidTag()}[Preflight] Flow A check failed:`, e instanceof Error ? e.message : e);
+            replyWith401("Stored OAuth session could not be revalidated");
+            return { blocked: true };
+        }
+        // Flow A is satisfied without hitting Nestr; no Flow B probe needed.
+        return { blocked: false };
+    }
+    const now = Date.now();
+    if (session.lastAuthVerifiedAt && now - session.lastAuthVerifiedAt < AUTH_VERIFY_TTL_MS) {
+        return { blocked: false };
+    }
+    // Flow B / API key: probe upstream with a cheap call.
+    try {
+        const probe = new NestrClient({
+            apiKey: session.authToken,
+            baseUrl: process.env.NESTR_API_BASE,
+            flow: session.isApiKey ? "unknown" : "B",
+        });
+        if (session.isApiKey) {
+            await probe.listWorkspaces({ limit: 1 });
+        }
+        else {
+            await probe.getCurrentUser();
+        }
+        session.lastAuthVerifiedAt = now;
+        return { blocked: false };
+    }
+    catch (e) {
+        if (e instanceof NestrApiError && e.status === 401) {
+            session.lastUpstream401At = now;
+            replyWith401(e.message);
+            return { blocked: true };
+        }
+        // Probe couldn't reach Nestr or hit a non-auth error. Don't fail closed —
+        // a 5xx from Nestr or a network blip shouldn't take the user offline.
+        console.warn(`${cidTag()}[Preflight] probe failed (non-401), allowing through:`, e instanceof Error ? e.message : e);
+        return { blocked: false };
+    }
 }
 // In-flight request tracking for /mcp so the shutdown handler can wait for
 // outstanding tool calls to finish before the pod terminates.
@@ -1271,6 +1461,10 @@ app.use("/mcp", (_req, res, next) => {
  * MCP POST endpoint - handles JSON-RPC requests
  */
 app.post("/mcp", async (req, res) => {
+    const correlationId = randomUUID();
+    await runWithContext({ correlationId }, () => handleMcpPost(req, res));
+});
+async function handleMcpPost(req, res) {
     const sessionId = req.headers["mcp-session-id"];
     const authToken = getAuthToken(req);
     const isApiKey = !!req.headers["x-nestr-api-key"];
@@ -1311,26 +1505,18 @@ app.post("/mcp", async (req, res) => {
                     });
                     return;
                 }
-                // For sessions held over from a previous pod, the OAuth token may have
-                // expired. Pre-check before invoking the transport so we can return a
-                // proper HTTP 401 + WWW-Authenticate that triggers MCP client re-auth,
-                // instead of wrapping the failure as a tool error the client ignores.
-                if (session.hasStoredOAuthSession) {
-                    const oauthSession = await getOAuthSession(session.authToken);
-                    if (!oauthSession) {
-                        res.status(401);
-                        res.setHeader("WWW-Authenticate", buildWwwAuthenticateHeader(req));
-                        res.json({
-                            jsonrpc: "2.0",
-                            error: {
-                                code: -32001,
-                                message: "OAuth session expired. Reconnect to re-authenticate.",
-                            },
-                            id: req.body?.id ?? null,
-                        });
-                        return;
-                    }
-                }
+                // Pre-flight upstream auth check. For Flow A this leans on the existing
+                // getOAuthSession refresh-or-return logic; for Flow B (Cowork etc.) it
+                // probes Nestr with /users/me on tool calls. Either way, if the bearer
+                // is dead we respond with HTTP 401 + WWW-Authenticate so the MCP SDK
+                // auto-refreshes — instead of wrapping the failure as a tool error the
+                // client ignores.
+                const toolName = isToolCallRequest(req.body)
+                    ? req.body?.params?.name
+                    : undefined;
+                const preflight = await preflightAuthCheck(req, res, session, toolName, isToolCallRequest(req.body));
+                if (preflight.blocked)
+                    return;
                 session.lastActivityAt = Date.now();
                 await maybeTouchMcpSession(sessionId, session);
                 await session.transport.handleRequest(req, res, req.body);
@@ -1382,8 +1568,13 @@ app.post("/mcp", async (req, res) => {
             });
             return;
         }
-        // Extract MCP client info early (needed for coalescing check)
+        // Extract MCP client info early (needed for coalescing check). The MCP
+        // initialize handshake provides a structured `clientInfo: { name, version }`;
+        // we capture both, surface them on the session, and forward to OAuth so the
+        // upstream OAuth server can record the version on the issued token row
+        // (slashme-online PR #1392).
         const mcpClientName = req.body?.params?.clientInfo?.name;
+        const mcpClientVersion = req.body?.params?.clientInfo?.version;
         if (!isInitializeRequest(req.body)) {
             res.status(400).json({
                 jsonrpc: "2.0",
@@ -1507,6 +1698,7 @@ app.post("/mcp", async (req, res) => {
             authToken,
             isApiKey,
             mcpClient: mcpClientName,
+            mcpClientVersion,
             userId,
             userName,
             wantsJsonOnly,
@@ -1517,7 +1709,7 @@ app.post("/mcp", async (req, res) => {
         await session.transport.handleRequest(req, res, req.body);
     }
     catch (error) {
-        console.error("Error handling MCP POST request:", error);
+        console.error(`${cidTag()}Error handling MCP POST request:`, error);
         if (!res.headersSent) {
             res.status(500).json({
                 jsonrpc: "2.0",
@@ -1529,7 +1721,7 @@ app.post("/mcp", async (req, res) => {
             });
         }
     }
-});
+}
 /**
  * MCP GET endpoint - handles SSE streams for server-initiated messages
  */