taskover-mcp 1.1.0 → 1.2.0

package/auth-flow.js

@@ -3,7 +3,7 @@ const http = require("http");
 const credentialStore = require("./credential-store.js");
 
 const API_BASE = "https://api.taskover.gg";
-const AUTH_PAGE_BASE = "https://taskover.gg";
+const AUTH_PAGE_BASE = "https://taskover.com";
 
 function generatePKCE() {
   const verifier = crypto.randomBytes(32).toString("base64url");
@@ -95,7 +95,7 @@ function startCallbackServer(expectedState) {
           if (!callbackUsed) {
             callbackUsed = true;
             server.close();
-            rejectCode(new Error("Auth timed out (5 min). Restart MCP server to try again."));
+            rejectCode(new Error("Auth timed out (5 min). Try your request again to re-launch authorization."));
           }
         }, 300000);
       });
@@ -163,41 +163,9 @@ async function refreshAccessToken(refreshToken) {
   return res.json();
 }
 
-async function authenticate(hostType) {
-  const cached = await credentialStore.read();
-  if (cached && cached.access_token && cached.refresh_token) {
-    if (cached.expires_at && Date.now() < cached.expires_at - 30000) {
-      return { accessToken: cached.access_token, refreshToken: cached.refresh_token };
-    }
-
-    try {
-      const res = await fetch(`${API_BASE}/api/auth/validate`, {
-        method: "POST",
-        headers: { "Authorization": `Bearer ${cached.access_token}` },
-        signal: AbortSignal.timeout(5000),
-      });
-      if (res.ok) {
-        const data = await res.json();
-        return { accessToken: cached.access_token, refreshToken: cached.refresh_token, displayName: data.displayName || "user" };
-      }
-    } catch (_) {}
-
-    try {
-      console.error("[AUTH] Access token expired, refreshing...");
-      const tokens = await refreshAccessToken(cached.refresh_token);
-      await credentialStore.write({
-        access_token: tokens.access_token,
-        refresh_token: tokens.refresh_token,
-        expires_at: Date.now() + (tokens.expires_in * 1000),
-        host_type: hostType,
-      });
-      return { accessToken: tokens.access_token, refreshToken: tokens.refresh_token };
-    } catch (err) {
-      console.error(`[AUTH] Refresh failed: ${err.message}. Starting browser login...`);
-      await credentialStore.clear();
-    }
-  }
-
+// Full browser PKCE auth flow. Does NOT check cached credentials.
+// Called by auth-gate when no valid tokens exist.
+async function authenticateFull(hostType) {
   console.error("[AUTH] Opening browser for login...");
 
   const pkce = generatePKCE();
@@ -252,24 +220,9 @@ async function authenticate(hostType) {
   return { accessToken: tokens.access_token, refreshToken: tokens.refresh_token };
 }
 
-async function reauthenticate(currentRefreshToken) {
-  try {
-    const tokens = await refreshAccessToken(currentRefreshToken);
-    await credentialStore.write({
-      access_token: tokens.access_token,
-      refresh_token: tokens.refresh_token,
-      expires_at: Date.now() + (tokens.expires_in * 1000),
-    });
-    return tokens;
-  } catch (err) {
-    await credentialStore.clear();
-    throw new Error("Session expired. Restart the MCP server to re-authenticate via browser.");
-  }
-}
-
 async function logout() {
   await credentialStore.clear();
   console.error("[AUTH] Logged out. Credentials cleared.");
 }
 
-module.exports = { authenticate, reauthenticate, logout };
+module.exports = { authenticateFull, refreshAccessToken, logout };

package/auth-gate.js

@@ -0,0 +1,253 @@
+// mcp-server/auth-gate.js
+// Singleton just-in-time auth coordinator.
+// All tool calls that need auth go through ensureAuth().
+// Guarantees: single browser popup, request hold+resume, bounded timeout.
+//
+// WRITE SAFETY GUARANTEE:
+// The JIT auth flow guarantees at-most-once execution for mutating requests:
+// 1. ensureAuth() blocks until auth succeeds — the write has not been attempted yet.
+// 2. After auth, callRpc() executes the write exactly once.
+// 3. On 401 during an RPC call, the server rejected the request (nothing was written).
+//    handleAuthFailure() re-authenticates, then callRpc() retries — this is the first real execution.
+// 4. No write is ever sent to the server more than once for a single tool invocation.
+// 5. Network-level failures (timeout, connection reset) are NOT retried — they surface
+//    as errors to the user. This ensures at-most-once even for partial server processing.
+
+const credentialStore = require("./credential-store.js");
+
+const COOLDOWN_MS = 10000; // 10s min gap between auth attempts after failure
+const MAX_REAUTH_ATTEMPTS = 2; // max consecutive re-auth attempts before giving up
+const BOOT_GRACE_MS = 8000; // 8s after boot — suppress browser auth from auto-discovery calls
+
+// Structured lifecycle logging — concise, non-sensitive, never prints tokens or user data.
+function _log(event, detail) {
+  console.error(`[AUTH] ${event}${detail ? " — " + detail : ""}`);
+}
+
+// States
+const IDLE = "IDLE";
+const AUTHENTICATED = "AUTHENTICATED";
+const AUTH_IN_PROGRESS = "AUTH_IN_PROGRESS";
+const FAILED = "FAILED";
+
+let _state = IDLE;
+let _accessToken = null;
+let _refreshToken = null;
+let _pendingAuthPromise = null; // dedup guard for concurrent ensureAuth() calls
+let _pendingRefreshPromise = null; // dedup guard for concurrent 401 handling
+let _lastFailureTime = 0;
+let _reAuthAttempts = 0;
+let _bootTime = Date.now(); // tracks server start for boot grace period
+let _authFlow = null; // lazy-loaded to avoid circular deps
+let _cloudAdapter = null;
+
+function _getAuthFlow() {
+  if (!_authFlow) _authFlow = require("./auth-flow.js");
+  return _authFlow;
+}
+
+function _getCloudAdapter() {
+  if (!_cloudAdapter) _cloudAdapter = require("./cloud-adapter.js");
+  return _cloudAdapter;
+}
+
+// Called at boot to try loading cached credentials without browser.
+// Does NOT launch browser auth if missing — just loads what's there.
+// NOTE: Does NOT validate token against the server (unlike old authenticate()).
+// If the token was revoked server-side, the first tool call will get 401
+// and handleAuthFailure() will handle it gracefully.
+async function tryLoadCachedTokens() {
+  try {
+    const cached = await credentialStore.read();
+    if (cached && cached.access_token && cached.refresh_token) {
+      // Check if access token is still valid (with 30s margin)
+      if (cached.expires_at && Date.now() < cached.expires_at - 30000) {
+        _accessToken = cached.access_token;
+        _refreshToken = cached.refresh_token;
+        _state = AUTHENTICATED;
+        _getCloudAdapter().setTokens(_accessToken, _refreshToken);
+        _log("cached_auth_loaded");
+        return true;
+      }
+      // Try refresh silently
+      try {
+        const authFlow = _getAuthFlow();
+        const tokens = await authFlow.refreshAccessToken(cached.refresh_token);
+        await credentialStore.write({
+          access_token: tokens.access_token,
+          refresh_token: tokens.refresh_token,
+          expires_at: Date.now() + (tokens.expires_in * 1000),
+          host_type: cached.host_type,
+        });
+        _accessToken = tokens.access_token;
+        _refreshToken = tokens.refresh_token;
+        _state = AUTHENTICATED;
+        _getCloudAdapter().setTokens(_accessToken, _refreshToken);
+        _log("token_refresh_success", "silent startup refresh");
+        return true;
+      } catch (_) {
+        // Refresh failed — credentials are stale, clear them.
+        // Do NOT launch browser. Just go to IDLE.
+        await credentialStore.clear();
+        _log("token_refresh_failed", "cached credentials expired, will authenticate on first tool use");
+        return false;
+      }
+    }
+    return false;
+  } catch (err) {
+    // If credential store or cloud adapter fails to load, boot unauthenticated
+    _log("cached_auth_error", err.message);
+    return false;
+  }
+}
+
+// The main gate. Every protected tool call awaits this.
+// Returns { accessToken, refreshToken } or throws.
+// When auth is in progress, all concurrent callers share the same pending promise
+// so only ONE browser popup ever opens and all held requests resume together.
+//
+// callerMethod: optional RPC method name for logging which tool triggered auth.
+async function ensureAuth(callerMethod) {
+  // Fast path: already authenticated
+  if (_state === AUTHENTICATED && _accessToken) {
+    return { accessToken: _accessToken, refreshToken: _refreshToken };
+  }
+
+  // Dedup: if auth is already in progress, all callers share the same promise
+  if (_state === AUTH_IN_PROGRESS && _pendingAuthPromise) {
+    _log("ensureAuth_dedup", `method=${callerMethod || "unknown"}, sharing pending auth`);
+    return _pendingAuthPromise;
+  }
+
+  // Boot grace period: suppress browser popups from MCP host auto-discovery calls
+  // (e.g. Claude calling taskovergg_dashboard immediately on connect).
+  // During the grace window, return a passive error instead of opening the browser.
+  // After the grace period, real user-initiated calls trigger auth normally.
+  if (_state === IDLE) {
+    const sinceBoot = Date.now() - _bootTime;
+    if (sinceBoot < BOOT_GRACE_MS) {
+      _log("boot_grace_suppressed", `method=${callerMethod || "unknown"}, ${Math.ceil((BOOT_GRACE_MS - sinceBoot) / 1000)}s remaining`);
+      throw new Error("AUTH_NOT_READY:TaskOver is not connected yet. Use any TaskOver tool to start authorization.");
+    }
+  }
+
+  // Cooldown after failure to prevent popup loops
+  if (_state === FAILED) {
+    const elapsed = Date.now() - _lastFailureTime;
+    if (elapsed < COOLDOWN_MS) {
+      _log("reauth_cooldown_active", `${Math.ceil((COOLDOWN_MS - elapsed) / 1000)}s remaining`);
+      throw new Error("AUTH_FAILED_RETRY:Authorization was recently declined or timed out. Please try again in a moment.");
+    }
+  }
+
+  // Launch browser auth — transitions to AUTH_IN_PROGRESS
+  _log("ensureAuth_trigger", `method=${callerMethod || "unknown"}`);
+  _state = AUTH_IN_PROGRESS;
+  _pendingAuthPromise = _doJitAuth();
+
+  try {
+    const result = await _pendingAuthPromise;
+    return result;
+  } finally {
+    _pendingAuthPromise = null;
+  }
+}
+
+async function _doJitAuth() {
+  const hostType = process.env.TASKOVER_HOST_TYPE || "MCP";
+
+  try {
+    _log("jit_auth_start", `host=${hostType}`);
+    const authFlow = _getAuthFlow();
+    const auth = await authFlow.authenticateFull(hostType);
+
+    _accessToken = auth.accessToken;
+    _refreshToken = auth.refreshToken;
+    _state = AUTHENTICATED;
+    _lastFailureTime = 0;
+    _reAuthAttempts = 0;
+    _getCloudAdapter().setTokens(_accessToken, _refreshToken);
+
+    _log("jit_auth_success");
+    return { accessToken: _accessToken, refreshToken: _refreshToken };
+  } catch (err) {
+    _state = FAILED;
+    _lastFailureTime = Date.now();
+    _log("jit_auth_failed", err.message);
+    throw new Error(`AUTH_FAILED_RETRY:${err.message}`);
+  }
+}
+
+// Called by cloud-adapter when a 401 is received during an RPC call.
+// Tries refresh first, falls back to full browser re-auth.
+// DEDUP: If another caller already refreshed successfully (state is AUTHENTICATED),
+// return current tokens. If a refresh is already in progress, share the pending promise.
+async function handleAuthFailure() {
+  // Dedup: if another concurrent 401 handler already refreshed, use those tokens
+  if (_state === AUTHENTICATED && _accessToken) {
+    return { accessToken: _accessToken, refreshToken: _refreshToken };
+  }
+
+  // Dedup: if refresh is already in progress, share the pending promise
+  if (_pendingRefreshPromise) {
+    return _pendingRefreshPromise;
+  }
+
+  // Max-retry guard to prevent infinite re-auth loops
+  _reAuthAttempts++;
+  if (_reAuthAttempts > MAX_REAUTH_ATTEMPTS) {
+    _log("reauth_max_attempts", `limit=${MAX_REAUTH_ATTEMPTS}`);
+    _reAuthAttempts = 0;
+    throw new Error("AUTH_FAILED_RETRY:Too many re-authentication attempts. Please try again later.");
+  }
+
+  _pendingRefreshPromise = _doHandleAuthFailure();
+  try {
+    return await _pendingRefreshPromise;
+  } finally {
+    _pendingRefreshPromise = null;
+  }
+}
+
+async function _doHandleAuthFailure() {
+  // Try refresh first
+  if (_refreshToken) {
+    try {
+      _log("token_refresh_start");
+      const authFlow = _getAuthFlow();
+      const tokens = await authFlow.refreshAccessToken(_refreshToken);
+      await credentialStore.write({
+        access_token: tokens.access_token,
+        refresh_token: tokens.refresh_token,
+        expires_at: Date.now() + (tokens.expires_in * 1000),
+      });
+      _accessToken = tokens.access_token;
+      _refreshToken = tokens.refresh_token;
+      _state = AUTHENTICATED;
+      _reAuthAttempts = 0;
+      _getCloudAdapter().setTokens(_accessToken, _refreshToken);
+      _log("token_refresh_success");
+      return { accessToken: _accessToken, refreshToken: _refreshToken };
+    } catch (_) {
+      _log("token_refresh_failed", "clearing credentials, will re-authenticate");
+      await credentialStore.clear();
+    }
+  }
+
+  // Refresh failed — need full re-auth
+  _state = IDLE;
+  _accessToken = null;
+  _refreshToken = null;
+  return ensureAuth();
+}
+
+function isAuthenticated() {
+  return _state === AUTHENTICATED && !!_accessToken;
+}
+
+module.exports = {
+  tryLoadCachedTokens,
+  ensureAuth,
+  handleAuthFailure,
+  isAuthenticated,
+};

package/cloud-adapter.js

@@ -44,6 +44,14 @@ const MCP_ALLOWED_READS = new Set([
   "getStories", "getScenes", "getSceneContent", "getStoryBible",
   "search",
   "dashboard", "contextExport",
+  // Blueprint Intelligence reads
+  "getDiscoveredBpDetail", "getSyncDebugInfo",
+  "computeBlueprintComplexity", "computeBlueprintHealth",
+  "getBlueprintTimeline", "generateBlueprintSummary",
+  "computeBlueprintReview", "computeProjectBlueprintReview",
+  "getBlueprintStandards", "getBlueprintViolations",
+  "buildBlueprintDependencyGraph", "computeImpactAnalysis",
+  "getBlueprintUsageMap", "getBlueprintIntelligenceDashboard",
 ]);
 
 // REVISED per M0 matrix (52 write methods). Removed: updateBug (no MCP tool),
@@ -80,6 +88,9 @@ const MCP_ALLOWED_WRITES = new Set([
   "addScene", "updateScene",
   "updateStoryBible",
   "addStoryCharacter",
+  // Blueprint Intelligence writes
+  "syncDiscoveredBps", "createBlueprintSnapshot",
+  "toggleBlueprintStandard", "evaluateBlueprintStandards", "resolveBlueprintViolation",
 ]);
 
 // SECURITY: Methods that are NEVER allowed through MCP, regardless of future changes.
@@ -102,7 +113,7 @@ const MCP_ALLOWED_METHODS = new Set([...MCP_ALLOWED_READS, ...MCP_ALLOWED_WRITES
 
 let _apiKey = null;
 
-// Token-based auth state (OAuth flow — set via initWithToken)
+// Token-based auth state (browser auth — set via setTokens, managed by auth-gate)
 let _accessToken = null;
 let _refreshToken = null;
 
@@ -110,11 +121,16 @@ function init(apiKey) {
   _apiKey = apiKey;
 }
 
-function initWithToken(accessToken, refreshToken) {
+// Called by auth-gate after successful auth or refresh. Can be called multiple times.
+function setTokens(accessToken, refreshToken) {
   _accessToken = accessToken;
   _refreshToken = refreshToken;
 }
 
+function isInitialized() {
+  return !!(_apiKey || _accessToken);
+}
+
 function isAllowed(method) {
   return MCP_ALLOWED_METHODS.has(method);
 }
@@ -186,20 +202,26 @@ async function _doRpcCall(method, args, token) {
 }
 
 async function callRpc(method, args) {
-  const token = _accessToken || _apiKey;
+  // In API-key mode, just use the key directly — no auth gate involvement
+  if (_apiKey) {
+    return _doRpcCall(method, args, _apiKey);
+  }
+
+  // Browser-auth mode: ensure we have tokens via auth gate.
+  // Use the returned token directly (not the module-level _accessToken)
+  // to avoid stale-read issues if setTokens hasn't been called yet.
+  const authGate = require("./auth-gate.js");
+  const { accessToken } = await authGate.ensureAuth(method);
+  if (!accessToken) throw new Error("AUTH_FAILED_RETRY:No access token available");
+
   try {
-    return await _doRpcCall(method, args, token);
+    return await _doRpcCall(method, args, accessToken);
   } catch (err) {
-    if (err.message === "AUTH_FAILED" && _accessToken && _refreshToken) {
-      try {
-        const authFlow = require("./auth-flow.js");
-        const tokens = await authFlow.reauthenticate(_refreshToken);
-        _accessToken = tokens.access_token;
-        _refreshToken = tokens.refresh_token;
-        return await _doRpcCall(method, args, _accessToken);
-      } catch (refreshErr) {
-        throw new Error("Session expired. Restart the MCP server to re-authenticate.");
-      }
+    if (err.message === "AUTH_FAILED") {
+      // Token expired/revoked mid-session — let auth gate handle refresh or re-auth
+      const refreshed = await authGate.handleAuthFailure();
+      if (!refreshed.accessToken) throw new Error("AUTH_FAILED_RETRY:Re-authentication failed");
+      return await _doRpcCall(method, args, refreshed.accessToken);
     }
     throw err;
   }
@@ -235,11 +257,12 @@ async function validateKey() {
 
 module.exports = {
   init,
-  initWithToken,
+  setTokens,
   isAllowed,
   isWrite,
   callRpc,
   validateKey,
+  isInitialized,
   MCP_ALLOWED_METHODS,
   MCP_ALLOWED_READS,
   MCP_ALLOWED_WRITES,