@nestr/mcp 0.1.72 → 0.1.89

package/build/http.js

@@ -32,11 +32,12 @@ import { randomUUID, randomBytes } from "node:crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 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 { toolDefinitions, PUBLIC_TOOL_NAMES } from "./tools/index.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";
+import { tagOAuthClientInfo, deriveOAuthBaseUrl, } from "./oauth/client-info.js";
 import { constantTimeCompare, validateRedirectUri, } from "./oauth/storage.js";
 import { analytics } from "./analytics/index.js";
 import "./analytics/ga4.js";
@@ -46,6 +47,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;
@@ -209,16 +212,29 @@ app.post("/oauth/register", registerLimiter, express.json(), async (req, res) =>
             });
             return;
         }
-        // Validate required fields
-        if (!redirect_uris || !Array.isArray(redirect_uris) || redirect_uris.length === 0) {
+        // RFC 7591: redirect_uris is only required for redirect-based grants.
+        // Device-code-only clients (headless agents) never redirect and may omit it.
+        const requestedGrantTypes = Array.isArray(grant_types) && grant_types.length > 0
+            ? grant_types
+            : ["authorization_code", "refresh_token"];
+        const usesRedirectGrant = requestedGrantTypes.includes("authorization_code") || requestedGrantTypes.includes("implicit");
+        if (redirect_uris !== undefined && !Array.isArray(redirect_uris)) {
             res.status(400).json({
                 error: "invalid_client_metadata",
-                error_description: "redirect_uris is required and must be a non-empty array",
+                error_description: "redirect_uris must be an array",
+            });
+            return;
+        }
+        const redirectUris = redirect_uris ?? [];
+        if (usesRedirectGrant && redirectUris.length === 0) {
+            res.status(400).json({
+                error: "invalid_client_metadata",
+                error_description: "redirect_uris is required and must be a non-empty array for redirect-based grant types",
             });
             return;
         }
         // Validate redirect URIs (must be localhost or HTTPS)
-        for (const uri of redirect_uris) {
+        for (const uri of redirectUris) {
             try {
                 const parsed = new URL(uri);
                 const isLocalhost = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
@@ -239,18 +255,20 @@ app.post("/oauth/register", registerLimiter, express.json(), async (req, res) =>
                 return;
             }
         }
-        // Generate client credentials
+        // Generate client credentials. RFC 7591: do not issue credentials the
+        // client cannot use, so public clients (auth method "none") get no secret.
         const clientId = `mcp-${randomUUID()}`;
-        const clientSecret = randomBytes(32).toString("base64url");
+        const tokenEndpointAuthMethod = token_endpoint_auth_method || "client_secret_post";
+        const clientSecret = tokenEndpointAuthMethod === "none" ? undefined : randomBytes(32).toString("base64url");
         // Create registered client
         const client = {
             client_id: clientId,
-            client_secret: clientSecret,
+            ...(clientSecret ? { client_secret: clientSecret } : {}),
             client_name: client_name || "MCP Client",
-            redirect_uris,
-            grant_types: grant_types || ["authorization_code", "refresh_token"],
+            redirect_uris: redirectUris,
+            grant_types: requestedGrantTypes,
             response_types: response_types || ["code"],
-            token_endpoint_auth_method: token_endpoint_auth_method || "client_secret_post",
+            token_endpoint_auth_method: tokenEndpointAuthMethod,
             scope: scope || "user nest",
             registered_at: Date.now(),
         };
@@ -259,7 +277,7 @@ app.post("/oauth/register", registerLimiter, express.json(), async (req, res) =>
         // Return registration response (RFC 7591)
         res.status(201).json({
             client_id: clientId,
-            client_secret: clientSecret,
+            ...(clientSecret ? { client_secret: clientSecret } : {}),
             client_name: client.client_name,
             redirect_uris: client.redirect_uris,
             grant_types: client.grant_types,
@@ -322,6 +340,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 +413,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 +633,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 +676,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 +718,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 +790,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 +859,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,22 +887,24 @@ 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 = {};
+// Public (unauthenticated) guest sessions live in their own map, fully isolated
+// from authenticated `sessions`. They never carry a token, never persist to
+// Redis, and never participate in coalescing/rehydration — so a guest session id
+// can never be confused with (or escalate into) an authenticated one.
+export const publicSessions = {};
 let shuttingDown = false;
 let inFlightRequests = 0;
-/**
- * Find a prior session that a re-initializing client is likely trying to replace.
- *
- * Matches on (authToken, mcpClient) within a 10-minute window. The POST /mcp
- * init path closes and drops the match so the client gets a fresh, clean
- * session — this prevents "Server already initialized" 400s when a client
- * reconnects after an SSE drop (the transport can only be initialized once).
- */
-export const SESSION_COALESCE_WINDOW_MS = 10 * 60 * 1000; // 10 minutes
-// Bumped from 30 → 60min: AI assistants commonly gap 30+ min between Nestr
-// tool bursts (long codebase work between status updates). Keeping the in-memory
-// session avoids a rehydration round-trip on the next call.
-const SESSION_STALE_TIMEOUT_MS = 60 * 60 * 1000; // 60 minutes without activity
+// Idle timeout for sessions WITHOUT a live SSE stream. Eviction is in-memory
+// only (no transport.close(), no Redis delete) so a returning client — e.g.
+// an AI assistant gapping 30+ min between tool bursts — transparently
+// rehydrates from the persisted record (7-day TTL). Sessions holding a live
+// SSE stream are never swept: an open stream means a connected client.
+export const SSE_DEAD_IDLE_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
 // Debounce for touchMcpSession. We refresh the Redis TTL at most this often
 // so a chatty client doesn't hammer the store.
 const MCP_SESSION_TOUCH_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
@@ -874,23 +912,34 @@ const MCP_SESSION_TOUCH_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
 // AWS ALB, nginx) typically idle-timeout TCP at 60s. Sending a comment line
 // every 25s keeps the connection alive — the SDK doesn't ping on its own.
 const SSE_KEEPALIVE_INTERVAL_MS = 25 * 1000; // 25 seconds
-// Periodically clean up dead sessions (closed SSE + stale).
-// We only drop the in-memory entry — the persistent Redis record lives on until
-// its own TTL so a late-returning client can still rehydrate.
-// .unref() so this timer doesn't prevent process exit (tests, graceful shutdown)
-setInterval(() => {
-    const now = Date.now();
-    for (const [sid, session] of Object.entries(sessions)) {
+// Periodically evict idle sessions that hold no live SSE stream. In-memory
+// eviction only — the persistent Redis record lives on until its own TTL so
+// a late-returning client rehydrates transparently (same mechanism as
+// deploys). This sweep is the ONLY reaper of idle sessions; nothing else may
+// close or delete a session another client might still be using.
+export function sweepStaleSessions(map, now) {
+    let evicted = 0;
+    for (const [sid, session] of Object.entries(map)) {
         const sseAlive = session.sseResponse && !session.sseResponse.writableEnded;
-        const stale = (now - session.lastActivityAt) > SESSION_STALE_TIMEOUT_MS;
-        if (!sseAlive && stale) {
-            if (session.sseKeepaliveTimer) {
-                clearInterval(session.sseKeepaliveTimer);
-                session.sseKeepaliveTimer = undefined;
-            }
-            delete sessions[sid];
+        if (sseAlive)
+            continue;
+        if (now - session.lastActivityAt <= SSE_DEAD_IDLE_TIMEOUT_MS)
+            continue;
+        if (session.sseKeepaliveTimer) {
+            clearInterval(session.sseKeepaliveTimer);
+            session.sseKeepaliveTimer = undefined;
         }
+        delete map[sid];
+        evicted++;
     }
+    if (evicted > 0) {
+        console.log(`[Sweep] Evicted ${evicted} idle session(s) from memory (persisted records preserved for rehydration)`);
+    }
+}
+setInterval(() => {
+    const now = Date.now();
+    sweepStaleSessions(sessions, now);
+    sweepStaleSessions(publicSessions, now);
 }, 60000).unref();
 /**
  * Refresh the Redis TTL of a persisted MCP session, debounced per-session so
@@ -940,24 +989,6 @@ async function dropSessionOnTokenSwap(sessionId, session, authToken) {
     await getStore().removeMcpSession(sessionId).catch(() => { });
     return true;
 }
-export function findCoalescableSession(authToken, mcpClient) {
-    const now = Date.now();
-    let bestMatch;
-    for (const [sid, session] of Object.entries(sessions)) {
-        if (session.authToken === authToken &&
-            session.mcpClient === mcpClient &&
-            (now - session.lastActivityAt) < SESSION_COALESCE_WINDOW_MS) {
-            const sseAlive = !!(session.sseResponse && !session.sseResponse.writableEnded);
-            // Pick the best session: prefer live SSE, then most recently active
-            if (!bestMatch ||
-                (sseAlive && !bestMatch.sseAlive) || // prefer live SSE over dead
-                (sseAlive === bestMatch.sseAlive && session.lastActivityAt > bestMatch.lastActivity)) {
-                bestMatch = { sessionId: sid, session, lastActivity: session.lastActivityAt, sseAlive };
-            }
-        }
-    }
-    return bestMatch ? { sessionId: bestMatch.sessionId, session: bestMatch.session } : undefined;
-}
 /**
  * Cache resolved identities by auth token to avoid repeated /users/me calls.
  * Cursor-vscode reconnects every ~60s, and workspace API keys sent as Bearer tokens
@@ -994,32 +1025,47 @@ 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,
+        isPublic: opts.isPublic,
         userId: opts.userId,
         userName: opts.userName,
         onToolCall: (toolName, args, success, error) => {
@@ -1040,19 +1086,35 @@ 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,
+                isPublic: opts.isPublic,
                 wantsJsonOnly: opts.wantsJsonOnly,
                 hasStoredOAuthSession: opts.hasStoredOAuthSession,
                 userId: opts.userId,
@@ -1062,20 +1124,25 @@ function buildMcpSession(opts) {
                 sessionStartTime,
                 lastActivityAt: Date.now(),
                 lastPersistedAt: Date.now(),
+                sessionCorrelationId: randomUUID(),
             };
             sessions[newSessionId] = sessionData;
             sessionRef = sessionData;
-            // Persist for rehydration after restart
-            getStore().storeMcpSession(newSessionId, {
-                authToken: opts.authToken,
-                mcpClient: opts.mcpClient,
-                userId: opts.userId,
-                userName: opts.userName,
-                isApiKey: opts.isApiKey,
-                wantsJsonOnly: opts.wantsJsonOnly,
-                hasStoredOAuthSession: opts.hasStoredOAuthSession,
-                createdAt: Date.now(),
-            }).catch(e => console.error("[McpSession] Failed to persist session:", e instanceof Error ? e.message : e));
+            // Persist for rehydration after restart. Public guest sessions are never
+            // persisted: they hold no token, so rehydration's token cross-check could
+            // never match, and there's no user state worth surviving a restart.
+            if (!opts.isPublic)
+                getStore().storeMcpSession(newSessionId, {
+                    authToken: opts.authToken,
+                    mcpClient: opts.mcpClient,
+                    mcpClientVersion: opts.mcpClientVersion,
+                    userId: opts.userId,
+                    userName: opts.userName,
+                    isApiKey: opts.isApiKey,
+                    wantsJsonOnly: opts.wantsJsonOnly,
+                    hasStoredOAuthSession: opts.hasStoredOAuthSession,
+                    createdAt: Date.now(),
+                }).catch(e => console.error("[McpSession] Failed to persist session:", e instanceof Error ? e.message : e));
             if (opts.analyticsCtx) {
                 try {
                     analytics.trackSessionStart(opts.analyticsCtx, {
@@ -1131,7 +1198,9 @@ function buildMcpSession(opts) {
             server,
             authToken: opts.authToken,
             mcpClient: opts.mcpClient,
+            mcpClientVersion: opts.mcpClientVersion,
             isApiKey: opts.isApiKey,
+            isPublic: opts.isPublic,
             wantsJsonOnly: opts.wantsJsonOnly,
             hasStoredOAuthSession: opts.hasStoredOAuthSession,
             userId: opts.userId,
@@ -1141,10 +1210,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,7 +1224,9 @@ function buildMcpSession(opts) {
         server,
         authToken: opts.authToken,
         mcpClient: opts.mcpClient,
+        mcpClientVersion: opts.mcpClientVersion,
         isApiKey: opts.isApiKey,
+        isPublic: opts.isPublic,
         wantsJsonOnly: opts.wantsJsonOnly,
         hasStoredOAuthSession: opts.hasStoredOAuthSession,
         userId: opts.userId,
@@ -1202,6 +1274,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 +1317,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 +1475,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 +1519,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 +1582,21 @@ 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).
+        //
+        // Some clients additionally emit a stable `software_id` extension field
+        // (snake_case per the slashme `client_software_id` convention; we also
+        // accept camelCase `softwareId` for forward compat). Capturing it lets the
+        // runtime tagging call fire even when a client emits software_id without
+        // a version.
         const mcpClientName = req.body?.params?.clientInfo?.name;
+        const mcpClientVersion = req.body?.params?.clientInfo?.version;
+        const mcpClientSoftwareId = (req.body?.params?.clientInfo?.software_id
+            ?? req.body?.params?.clientInfo?.softwareId);
         if (!isInitializeRequest(req.body)) {
             res.status(400).json({
                 jsonrpc: "2.0",
@@ -1395,28 +1608,44 @@ app.post("/mcp", async (req, res) => {
             });
             return;
         }
-        // Drop any lingering session for the same (auth token, client) before creating a
-        // new one. This happens when a client reconnects after an SSE drop: the old
-        // session is still in memory but its transport is already initialized, so we
-        // can't route a fresh `initialize` through it — the SDK would 400 with
-        // "Server already initialized". Creating a second session alongside the stale
-        // one also leaks memory over time. Close-and-replace is the only safe option.
-        const stale = findCoalescableSession(authToken, mcpClientName);
-        if (stale) {
-            const { sessionId: staleSid, session: staleSession } = stale;
-            console.log(`Replacing stale session ${staleSid} for ${mcpClientName || "unknown client"} on re-init`);
-            try {
-                await staleSession.transport.close();
-            }
-            catch (e) {
-                console.error("[Session] Failed to close stale transport:", e instanceof Error ? e.message : e);
-            }
-            delete sessions[staleSid];
-            await getStore().removeMcpSession(staleSid).catch(e => console.error("[McpSession] Failed to remove persisted stale session:", e instanceof Error ? e.message : e));
-        }
+        // Concurrent sessions per (auth token, client name) are intentional.
+        // Parallel clients routinely share one identity (agent jobs, Claude Code
+        // subagents, Codex workers), so an initialize must NEVER touch another
+        // connection's session — doing so caused the 2026-07-10 incident where
+        // sessions were killed ~1s after creation. A fresh initialize carries no
+        // Mcp-Session-Id, so it can't collide with an existing transport
+        // ("Server already initialized" is impossible on this path). Stale
+        // sessions are reaped non-destructively by sweepStaleSessions instead.
         if (mcpClientName) {
             console.log(`MCP client: ${mcpClientName}`);
         }
+        // Tag the upstream OAuth token row with the MCP `clientInfo` we just
+        // captured. The OAuth grant happened BEFORE this initialize handshake,
+        // so the token was issued without `client_version` / `client_software_id`
+        // even though slashme-online accepts those fields. Calling
+        // /oauth/tokens/client-info here closes the loop so the API Keys UI
+        // shows e.g. "Claude Code 2.1.15" right after first connect, without
+        // waiting for the next refresh-token cycle.
+        //
+        // Skip for API keys (no OAuth row exists). Fire when EITHER version or
+        // software_id is present — the slashme endpoint accepts either alone.
+        // For software_id, prefer the explicit `clientInfo.software_id` extension
+        // when present and fall back to `name` so existing clients (which only
+        // emit name+version) continue to populate clientSoftwareId on the row.
+        // Fire-and-forget — failures are logged but never block the MCP session.
+        if (!isApiKey && (mcpClientVersion || mcpClientSoftwareId)) {
+            const oauthBase = deriveOAuthBaseUrl(process.env.NESTR_API_BASE);
+            void tagOAuthClientInfo({
+                bearerToken: authToken,
+                baseUrl: oauthBase,
+                clientVersion: mcpClientVersion,
+                clientSoftwareId: mcpClientSoftwareId || mcpClientName,
+            }).then((result) => {
+                if (!result.ok) {
+                    console.warn(`[ClientInfo] tag failed: status=${result.status ?? "n/a"} error=${result.error ?? "unknown"}`);
+                }
+            });
+        }
         let userId;
         let userName;
         // Check cross-session identity cache first (survives cursor-vscode reconnections)
@@ -1507,6 +1736,7 @@ app.post("/mcp", async (req, res) => {
             authToken,
             isApiKey,
             mcpClient: mcpClientName,
+            mcpClientVersion,
             userId,
             userName,
             wantsJsonOnly,
@@ -1517,7 +1747,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,6 +1759,219 @@ app.post("/mcp", async (req, res) => {
             });
         }
     }
+}
+// ─── PUBLIC (unauthenticated) MCP surface ──────────────────────────────────
+//
+// POST /mcp/public is a credential-free "guest" surface for support-only AI
+// agents that have no workspace AI credit. It exposes ONLY the three help tools
+// (nestr_help, nestr_diagnose, nestr_get_me) and can NEVER reach authenticated
+// Nestr data:
+//   - Any Authorization / X-Nestr-API-Key / Cookie header is stripped on entry
+//     and ignored — there is no code path here that reads a credential.
+//   - Sessions are built with isPublic:true, which (a) filters tools/list to the
+//     three help tools and (b) makes handleToolCall refuse every other tool and
+//     serve nestr_get_me from a fixed guest payload with no Nestr API call.
+//   - The NestrClient is constructed with a sentinel token it never uses, since
+//     none of the three public tools issue an authenticated request.
+//   - Guest sessions live in their own `publicSessions` map, isolated from the
+//     authenticated `sessions` map (no coalescing, no Redis rehydration).
+const PUBLIC_SENTINEL_TOKEN = "public-guest-no-auth";
+app.post("/mcp/public", async (req, res) => {
+    const correlationId = randomUUID();
+    await runWithContext({ correlationId }, () => handlePublicMcpPost(req, res));
+});
+async function handlePublicMcpPost(req, res) {
+    const sessionId = req.headers["mcp-session-id"];
+    // Hard requirement: never read or honour credentials on the public surface.
+    // Strip them before anything else so they can't leak into the MCP SDK's
+    // requestInfo / MCPCat or be picked up by any downstream code.
+    delete req.headers.authorization;
+    delete req.headers["x-nestr-api-key"];
+    delete req.headers.cookie;
+    try {
+        const acceptHeader = req.headers.accept || "";
+        const wantsJsonOnly = acceptHeader.includes("application/json") && !acceptHeader.includes("text/event-stream");
+        if (wantsJsonOnly) {
+            req.headers.accept = `${acceptHeader}, text/event-stream`;
+        }
+        // Existing public session — route straight through. No token checks: public
+        // sessions have no credential to compare.
+        if (sessionId) {
+            const session = publicSessions[sessionId];
+            if (session) {
+                session.lastActivityAt = Date.now();
+                await session.transport.handleRequest(req, res, req.body);
+                return;
+            }
+            res.status(404).json({
+                jsonrpc: "2.0",
+                error: { code: -32001, message: "Session not found" },
+                id: req.body?.id ?? null,
+            });
+            return;
+        }
+        if (shuttingDown) {
+            res.status(503).json({
+                jsonrpc: "2.0",
+                error: { code: -32000, message: "Server is shutting down, please retry" },
+                id: req.body?.id ?? null,
+            });
+            return;
+        }
+        // Unauthenticated tools/list (no session yet) — return the public tool list
+        // directly, mirroring the authed surface's scanner-friendly shortcut.
+        if (req.body?.method === "tools/list") {
+            res.json({
+                jsonrpc: "2.0",
+                result: { tools: toolDefinitions.filter((t) => PUBLIC_TOOL_NAMES.has(t.name)) },
+                id: req.body?.id ?? null,
+            });
+            return;
+        }
+        // New session must be an initialize request (same contract as authed /mcp).
+        if (!isInitializeRequest(req.body)) {
+            res.status(400).json({
+                jsonrpc: "2.0",
+                error: {
+                    code: -32000,
+                    message: "Bad Request: No valid session ID provided, and request is not an initialization request",
+                },
+                id: req.body?.id ?? null,
+            });
+            return;
+        }
+        const mcpClientName = req.body?.params?.clientInfo?.name;
+        const mcpClientVersion = req.body?.params?.clientInfo?.version;
+        const session = buildMcpSession({
+            authToken: PUBLIC_SENTINEL_TOKEN,
+            isApiKey: false,
+            isPublic: true,
+            mcpClient: mcpClientName,
+            mcpClientVersion,
+            wantsJsonOnly,
+            hasStoredOAuthSession: false,
+        });
+        // buildMcpSession's onsessioninitialized registers fresh sessions in the
+        // authenticated `sessions` map. Re-home this guest session into the isolated
+        // publicSessions map once its id is known, so it never lives alongside authed
+        // sessions. The onclose handler also targets `sessions`, so we override it to
+        // clean up publicSessions instead.
+        const transport = session.transport;
+        await session.server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+        const sid = transport.sessionId;
+        if (sid) {
+            const created = sessions[sid] ?? session;
+            delete sessions[sid];
+            publicSessions[sid] = created;
+            transport.onclose = () => {
+                if (created.sseKeepaliveTimer) {
+                    clearInterval(created.sseKeepaliveTimer);
+                    created.sseKeepaliveTimer = undefined;
+                }
+                delete publicSessions[sid];
+            };
+        }
+    }
+    catch (error) {
+        console.error(`${cidTag()}Error handling public MCP POST request:`, error);
+        if (!res.headersSent) {
+            res.status(500).json({
+                jsonrpc: "2.0",
+                error: {
+                    code: -32603,
+                    message: error instanceof Error ? error.message : "Internal server error",
+                },
+                id: req.body?.id ?? null,
+            });
+        }
+    }
+}
+// Public SSE stream (server-initiated messages for a guest session).
+app.get("/mcp/public", async (req, res) => {
+    delete req.headers.authorization;
+    delete req.headers["x-nestr-api-key"];
+    delete req.headers.cookie;
+    const sessionId = req.headers["mcp-session-id"];
+    const session = sessionId ? publicSessions[sessionId] : undefined;
+    if (!session) {
+        res.status(404).json({
+            jsonrpc: "2.0",
+            error: { code: -32001, message: "Session not found" },
+            id: null,
+        });
+        return;
+    }
+    session.sseResponse = res;
+    if (session.sseKeepaliveTimer)
+        clearInterval(session.sseKeepaliveTimer);
+    session.sseKeepaliveTimer = setInterval(() => {
+        if (res.writableEnded || res.destroyed)
+            return;
+        try {
+            res.write(": keepalive\n\n");
+        }
+        catch (e) {
+            console.error("[PublicSession] SSE keepalive write failed:", e instanceof Error ? e.message : e);
+        }
+    }, SSE_KEEPALIVE_INTERVAL_MS);
+    session.sseKeepaliveTimer.unref?.();
+    res.on("close", () => {
+        if (session.sseKeepaliveTimer) {
+            clearInterval(session.sseKeepaliveTimer);
+            session.sseKeepaliveTimer = undefined;
+        }
+        if (session.sseResponse === res)
+            session.sseResponse = undefined;
+        try {
+            session.transport.closeStandaloneSSEStream();
+        }
+        catch (e) {
+            console.error("[PublicSession] closeStandaloneSSEStream on socket close failed:", e instanceof Error ? e.message : e);
+        }
+    });
+    try {
+        await session.transport.handleRequest(req, res);
+    }
+    catch (error) {
+        console.error("Error handling public MCP GET request:", error);
+        if (!res.headersSent) {
+            res.status(500).json({
+                jsonrpc: "2.0",
+                error: { code: -32603, message: "Internal server error" },
+                id: null,
+            });
+        }
+    }
+});
+// Public session termination.
+app.delete("/mcp/public", async (req, res) => {
+    delete req.headers.authorization;
+    delete req.headers["x-nestr-api-key"];
+    delete req.headers.cookie;
+    const sessionId = req.headers["mcp-session-id"];
+    const session = sessionId ? publicSessions[sessionId] : undefined;
+    if (!session) {
+        res.status(404).json({
+            jsonrpc: "2.0",
+            error: { code: -32001, message: "Session not found" },
+            id: null,
+        });
+        return;
+    }
+    try {
+        await session.transport.handleRequest(req, res);
+    }
+    catch (error) {
+        console.error("Error handling public MCP DELETE request:", error);
+        if (!res.headersSent) {
+            res.status(500).json({
+                jsonrpc: "2.0",
+                error: { code: -32603, message: "Internal server error" },
+                id: null,
+            });
+        }
+    }
 });
 /**
  * MCP GET endpoint - handles SSE streams for server-initiated messages
@@ -1571,7 +2014,8 @@ app.get("/mcp", async (req, res) => {
         return;
     }
     console.log(`SSE stream requested for session: ${sessionId}`);
-    // Track the SSE response for liveness detection (used by session coalescing)
+    session.lastActivityAt = Date.now();
+    // Track the SSE response for liveness detection (used by the stale-session sweep)
     session.sseResponse = res;
     // Heartbeat: SSE comment lines (`:keepalive`) keep the connection alive
     // through proxies/LBs that would otherwise drop idle TCP after ~60s. The