@context-engine-bridge/context-engine-mcp-bridge 0.0.17 → 0.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@context-engine-bridge/context-engine-mcp-bridge",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "description": "Context Engine MCP bridge (http/stdio proxy combining indexer + memory servers)",
   "bin": {
     "ctxce": "bin/ctxce.js",

package/src/mcpServer.js

@@ -175,6 +175,36 @@ function isAuthRejectionError(error) {
   }
 }
 
+/**
+ * Format an auth rejection error with actionable information for users.
+ * Includes the backend URL and a hint to sign in via VS Code command palette.
+ */
+function formatAuthRejectionError(originalError, backendUrl) {
+  const originalMsg =
+    (originalError && typeof originalError.message === "string" && originalError.message) ||
+    (typeof originalError === "string" ? originalError : String(originalError || "Unknown auth error"));
+
+  const serverInfo = backendUrl ? ` (server: ${backendUrl})` : "";
+  const hint = "Run 'Context Engine: Sign In' from the VS Code command palette to authenticate.";
+
+  return `Authentication failed${serverInfo}: ${originalMsg}. ${hint}`;
+}
+
+/**
+ * Emit a special log line that the VS Code extension can detect to show a notification toast.
+ * Format: [ctxce:auth-error] JSON payload
+ */
+function emitAuthErrorNotification(backendUrl, originalError) {
+  const payload = {
+    type: "auth_rejection",
+    backend: backendUrl || "unknown",
+    message: String(originalError?.message || originalError || "Authentication failed"),
+    hint: "Run 'Context Engine: Sign In' from the VS Code command palette",
+  };
+  // This special prefix allows the VS Code extension to detect auth errors in stderr
+  debugLog(`[ctxce:auth-error] ${JSON.stringify(payload)}`);
+}
+
 function getBridgeRetryAttempts() {
   try {
     const raw = process.env.CTXCE_TOOL_RETRY_ATTEMPTS;
@@ -520,8 +550,21 @@ async function createBridgeServer(options) {
     sessionId = resolveSessionId();
   }
 
+  // Only fall back to deterministic session if auth is not configured
+  // If auth backend is configured but no session found, log warning instead of creating deterministic session
   if (!sessionId) {
-    sessionId = `ctxce-${Buffer.from(workspace).toString("hex").slice(0, 24)}`;
+    if (authBackendUrl) {
+      // Auth is configured but no valid session - don't use deterministic fallback
+      debugLog(`[ctxce] WARNING: Auth backend configured (${authBackendUrl}) but no valid session found.`);
+      debugLog("[ctxce] To authenticate, run 'Context Engine: Sign In' from the VS Code command palette, or run `ctxce auth login` from the terminal.");
+      debugLog("[ctxce] Continuing with deterministic session for backward compatibility, but this may fail if backend requires auth.");
+      // Emit notification for VS Code extension
+      emitAuthErrorNotification(authBackendUrl, { message: "No valid session found - authentication required" });
+      sessionId = `ctxce-${Buffer.from(workspace).toString("hex").slice(0, 24)}`;
+    } else {
+      // No auth configured - use deterministic session for local-only operation
+      sessionId = `ctxce-${Buffer.from(workspace).toString("hex").slice(0, 24)}`;
+    }
   }
 
   // Best-effort: inform the indexer of default collection and session.
@@ -531,6 +574,17 @@ async function createBridgeServer(options) {
     defaultsPayload.collection = defaultCollection;
   }
 
+  // Include org context from auth entry if available (for org-scoped collection isolation)
+  try {
+    const authEntry = backendHint ? loadAuthEntry(backendHint) : null;
+    if (authEntry && authEntry.org_id) {
+      defaultsPayload.org_id = authEntry.org_id;
+      defaultsPayload.org_slug = authEntry.org_slug;
+    }
+  } catch {
+    // ignore auth entry lookup failures
+  }
+
   const repoName = detectRepoName(workspace, config);
 
   try {
@@ -782,10 +836,13 @@ async function createBridgeServer(options) {
 
         // Backend auth rejection (mcp_auth.py ValidationError) - expire local auth
         if (isAuthRejectionError(err)) {
+          const serverUrl = backendHint || uploadServiceUrl || "unknown server";
           debugLog(
-            "[ctxce] tools/call: backend auth rejection; marking local session as expired: " +
+            `[ctxce] tools/call: backend auth rejection from ${serverUrl}; marking local session as expired: ` +
             String(err),
           );
+          // Emit special notification for VS Code extension to detect and show toast
+          emitAuthErrorNotification(serverUrl, err);
           if (backendHint) {
             try {
               const entry = loadAuthEntry(backendHint);
@@ -796,6 +853,13 @@ async function createBridgeServer(options) {
               // ignore failures
             }
           }
+          // Enhance error with actionable message before throwing
+          if (!isTransientToolError(err) || attempt === maxAttempts - 1) {
+            const enhancedMessage = formatAuthRejectionError(err, serverUrl);
+            const enhancedError = new Error(enhancedMessage);
+            enhancedError.cause = err;
+            throw enhancedError;
+          }
         }
 
         if (!isTransientToolError(err) || attempt === maxAttempts - 1) {
@@ -908,10 +972,42 @@ export async function runHttpMcpServer(options) {
       // Check Bearer token for MCP endpoint (accept /mcp and /mcp/ for compatibility)
       if (parsedUrl.pathname === "/mcp" || parsedUrl.pathname === "/mcp/") {
         const authHeader = req.headers["authorization"] || "";
-        const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : null;
-
-        // TODO: Validate token and inject session
-        // For now, allow unauthenticated (backward compatible)
+        const bearerToken = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : null;
+
+        // ----------------------------------------------------------------
+        // AUTHENTICATION DESIGN: Permissive by default for backward compatibility
+        // ----------------------------------------------------------------
+        // The condition `bearerToken && hasTokenStore()` is INTENTIONALLY permissive:
+        //
+        // 1. PRE-EXISTING USERS (v3.0.0, local/dev mode):
+        //    - No OAuth flow occurs → tokenStore remains empty
+        //    - hasTokenStore() returns false → auth check skipped entirely
+        //    - Requests proceed without authentication (local dev experience)
+        //
+        // 2. SAAS PLATFORM USERS (multi-tenant):
+        //    - User completes OAuth flow → token stored in tokenStore
+        //    - hasTokenStore() returns true → bearer token validation required
+        //    - Invalid/missing tokens are rejected with 401
+        //
+        // WHY NOT `hasTokenStore() && !bearerToken` (require token when store exists)?
+        //    - Mixed environments: Some clients may be local (no auth) while others
+        //      are authenticated. Requiring auth globally after first login would
+        //      break local dev workflows in hybrid setups.
+        //    - The current design: "validate if provided, but don't require"
+        //
+        // SECURITY NOTE: If strict authentication is required for all clients once
+        // any user authenticates, add an environment flag like CTXCE_REQUIRE_AUTH=1
+        // and check it here to enforce bearer tokens regardless of token store state.
+        // ----------------------------------------------------------------
+        if (bearerToken && oauthHandler.hasTokenStore()) {
+          const sessionId = oauthHandler.lookupToken(bearerToken);
+          if (!sessionId) {
+            // Token provided but invalid - reject
+            res.writeHead(401, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message: "Invalid or expired bearer token" }, id: null }));
+            return;
+          }
+        }
 
         if (req.method !== "POST") {
           res.statusCode = 405;

package/src/oauthHandler.js

@@ -534,7 +534,7 @@ export function handleOAuthStoreSession(req, res) {
 export function handleOAuthToken(req, res) {
   let body = "";
   req.on("data", (chunk) => { body += chunk; });
-  req.on("end", () => {
+  req.on("end", async () => {
     try {
       const data = new URLSearchParams(body);
       const code = data.get("code");
@@ -585,8 +585,24 @@ export function handleOAuthToken(req, res) {
         return;
       }
 
-      // TODO: Validate PKCE code_verifier against code_challenge
-      // For now, skip validation (local bridge, trusted)
+      // TODO: PKCE validation - disabled for now, no clients implement it yet
+      // if (pendingData.codeChallenge && pendingData.codeChallengeMethod === "S256") {
+      //   const codeVerifier = data.get("code_verifier");
+      //   if (!codeVerifier) {
+      //     pendingCodes.delete(code);
+      //     res.statusCode = 400;
+      //     res.end(JSON.stringify({ error: "invalid_grant", error_description: "code_verifier required for PKCE" }));
+      //     return;
+      //   }
+      //   const crypto = await import("node:crypto");
+      //   const expectedChallenge = crypto.createHash("sha256").update(codeVerifier).digest("base64url");
+      //   if (expectedChallenge !== pendingData.codeChallenge) {
+      //     pendingCodes.delete(code);
+      //     res.statusCode = 400;
+      //     res.end(JSON.stringify({ error: "invalid_grant", error_description: "code_verifier validation failed" }));
+      //     return;
+      //   }
+      // }
 
       // Clean up expired tokens periodically to prevent unbounded growth
       cleanupExpiredTokens();
@@ -651,4 +667,31 @@ export function isOAuthEndpoint(pathname) {
   );
 }
 
+/**
+ * Check if the token store has any entries (indicates auth is active)
+ * @returns {boolean}
+ */
+export function hasTokenStore() {
+  return tokenStore.size > 0;
+}
+
+/**
+ * Look up a bearer token and return the associated session ID
+ * @param {string} token - Bearer token to validate
+ * @returns {string|null} - Session ID if valid, null otherwise
+ */
+export function lookupToken(token) {
+  const entry = tokenStore.get(token);
+  if (!entry) return null;
+
+  // Check expiration
+  const tokenAge = Date.now() - entry.createdAt;
+  if (tokenAge > TOKEN_EXPIRY_MS) {
+    tokenStore.delete(token);
+    return null;
+  }
+
+  return entry.sessionId || null;
+}
+
 startCleanupInterval();

package/AGENTS.md

@@ -1,18 +0,0 @@
-<!-- Parent: ../AGENTS.md -->
-# MCP Bridge CLI (ctxce)
-
-Node package that exposes indexer+memory as a single MCP server (stdio + HTTP). Optional OAuth/PKCE.
-
-## WHERE TO LOOK
-
-| Task | Location | Notes |
-|------|----------|-------|
-| CLI entry | `ctx-mcp-bridge/bin/ctxce.js` | wrapper -> src/cli |
-| CLI logic | `ctx-mcp-bridge/src/cli.js` | command parsing |
-| MCP proxy | `ctx-mcp-bridge/src/mcpServer.js` | forwards tools |
-| OAuth/PKCE | `ctx-mcp-bridge/src/oauthHandler.js` | auth flow |
-| Path mapping | `ctx-mcp-bridge/src/resultPathMapping.js` | local <-> remote |
-
-## KNOWN TODO
-
-- PKCE verifier validation is still TODO in `ctx-mcp-bridge/src/oauthHandler.js`.