cbrowser 19.3.8 → 19.4.0

package/dist/mcp-server-remote.js

@@ -40,16 +40,18 @@ import { createRemoteJWKSet, jwtVerify } from "jose";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { CBrowser } from "./browser.js";
-import { ensureDirectories } from "./config.js";
+import { ensureDirectories, getDataDir } from "./config.js";
 // Version from package.json - single source of truth
 import { VERSION } from "./version.js";
 // Modular MCP tools (v17.5.0)
 // getActiveKeyHash is deliberately no longer imported: billing identity is per-request
-// (see resolveRequestKeyHash). setActiveKeyHash stays for the usage-logging path, which
-// is per-session rather than per-charge.
+// (see resolveRequestKeyHash). setActiveKeyHash, setActiveTier and setSessionApiKey
+// write the calling request's own identity context (request-context.ts), which every
+// HTTP request enters at createServer below. (sec-identity, 2026-10-10)
 import { registerAllPublicTools, setRemoteMode, setHostedMode, setActiveTier as setTierGate, setActiveKeyHash, isToolAccessible, upgradePrompt } from "./mcp-tools/index.js";
 import { withPersonaScope, scopedAccountId } from "./persona-scope.js";
 import { withChargeScope } from "./charge-scope.js";
+import { withRequestIdentity } from "./request-context.js";
 /**
  * keyHash -> accountId, so a request can be scoped to the tenant that owns it.
  *
@@ -76,6 +78,8 @@ export async function resolveRequestAccountId(req) {
     const after = accountCache.get(keyHash);
     return after && after.expiresAt > Date.now() ? after.accountId : null;
 }
+import { TOOL_CATEGORIES, categorizedToolNames } from "./mcp-tools/tool-categories.js";
+import { BUILTIN_PERSONAS, ACCESSIBILITY_PERSONAS, EMOTIONAL_PERSONAS, AGENT_PERSONAS } from "./personas.js";
 // Shared browser instance (single Chromium process)
 let browser = null;
 // Stealth state (enterprise integration)
@@ -453,6 +457,10 @@ async function getBrowser() {
             headless: true,
             persistent: true,
             proxy: proxyConfig,
+            // The shared legacy browser belongs to no account, so its files stay
+            // in the process data dir even if it is first built inside a scope;
+            // the config default is now the caller's directory. (tenant, 2026-10-10)
+            dataDir: getDataDir(),
         });
     }
     return browser;
@@ -639,6 +647,35 @@ const tierCache = new Map();
 const MAX_REQUEST_BODY_BYTES = 4 * 1024 * 1024;
 /** Bound the CMS deduct call; an unanswered one used to hang the whole request. */
 const CREDIT_DEDUCT_TIMEOUT_MS = 5_000;
+/**
+ * "none" on the enterprise server: enterprise is unlimited use (Alexa, 2026-10-12).
+ * The deduct call is still made, because the CMS deduct route is also the domain,
+ * tier and URL gate; `charge=none` makes the CMS price the call at 0. Set once at
+ * startup from `RemoteMcpServerOptions.chargeCredits`.
+ */
+let creditChargeMode = "charge";
+export function setCreditChargeMode(mode) {
+    creditChargeMode = mode;
+}
+/**
+ * Did this deduct response actually take credits? Decides whether the call enters a
+ * charge scope (where an isError result is refunded). A 0-credit deduct (charge=none,
+ * or a free tool) took nothing, and the CMS refund route credits the catalog price
+ * without finding the matching deduct, so refunding it would mint credits. A CMS that
+ * does not report `cost` keeps the old behaviour.
+ */
+export function chargedByDeduct(httpOk, data) {
+    return httpOk && data.allowed === true && data.cost !== 0;
+}
+/** Query string for POST /api/credits/deduct. */
+export function deductQuery(keyHash, toolName, targetUrl) {
+    return new URLSearchParams({
+        key_hash: keyHash,
+        tool: toolName,
+        ...(targetUrl ? { target_url: targetUrl } : {}),
+        ...(creditChargeMode === "none" ? { charge: "none" } : {}),
+    }).toString();
+}
 const TIER_CACHE_TTL_MS = 30 * 1000;
 /**
  * Extract the raw API key from an incoming HTTP request.
@@ -1084,6 +1121,13 @@ function sendUnauthorized(res, message) {
         }),
     }));
 }
+/**
+ * The tier a request is gated at.
+ * Priority: resolved from API key > CBROWSER_TIER env > null (self-hosted, no gating).
+ */
+function effectiveTier(resolvedTier) {
+    return resolvedTier ?? process.env.CBROWSER_TIER ?? null;
+}
 /**
  * Configure all CBrowser tools on an MCP server instance.
  * This is shared between stdio and HTTP transports.
@@ -1101,8 +1145,7 @@ function configureMcpTools(server, customRegisterTools, sessionId, resolvedTier)
         ? () => getSessionBrowser(sessionId)
         : getTokenlessBrowser;
     const context = { getBrowser: sessionGetBrowser, getBrowserByToken };
-    // Tier priority: resolved from API key > CBROWSER_TIER env > null (self-hosted, no gating)
-    const tier = resolvedTier ?? process.env.CBROWSER_TIER ?? null;
+    const tier = effectiveTier(resolvedTier);
     if (customRegisterTools) {
         // Set tier BEFORE custom registration so createGatedServer uses resolved tier
         setTierGate(tier);
@@ -1113,30 +1156,30 @@ function configureMcpTools(server, customRegisterTools, sessionId, resolvedTier)
     }
 }
 /**
- * Create a configured MCP server instance
+ * Counts this server prints about itself, all derived, never typed.
  *
- * @param customRegisterTools - Optional custom tool registration
- * @param sessionId - Optional session ID for session isolation
+ * Every number below used to be a literal, and they disagreed with each other
+ * and with tools/list: the instructions said "120 tools across 16 categories",
+ * docs://tools-overview said 105 in its description and "120 across 11" in its
+ * body, persona_creation was "(6 tools)" with nine registered, and
+ * docs://personas said 21 while listing 6 of the 10 general personas. Measured
+ * 2026-10-10: tools/list on the enterprise server returned 130 tools, 126 of
+ * them in TOOL_CATEGORIES' 20 categories and 4 in none (B33).
  */
-function createMcpServer(customRegisterTools, sessionId, resolvedTier) {
-    const server = new McpServer({
-        name: "cbrowser",
-        title: "CBrowser — Cognitive Browser Automation",
-        version: VERSION,
-        description: "AI-powered browser automation with cognitive user simulation. 120 MCP tools for navigation, visual testing, accessibility auditing, persona-based testing, site knowledge learning, and security scanning. Simulates how real humans think, struggle, and give up on your site.",
-        websiteUrl: "https://cbrowser.ai",
-        icons: [
-            { src: "https://cbrowser.ai/icon-192.png", sizes: ["192x192"] },
-            { src: "https://cbrowser.ai/icon-512.png", sizes: ["512x512"] },
-            { src: "https://cbrowser.ai/logo.svg", sizes: ["1080x1080"] },
-        ],
-    }, {
-        capabilities: {
-            tools: { listChanged: true },
-            prompts: {},
-            resources: {},
-        },
-        instructions: `CBrowser — cognitive browser automation with 120 tools across 16 categories.
+function catalogCounts() {
+    return { tools: categorizedToolNames().length, categories: TOOL_CATEGORIES.length };
+}
+/** One line per specialist category, counted from TOOL_CATEGORIES. */
+function specialistCategoryLines() {
+    return TOOL_CATEGORIES
+        .filter((cat) => cat.tier > 1)
+        .map((cat) => `• ${cat.name} (${cat.tools.length} tool${cat.tools.length === 1 ? "" : "s"}) — ${cat.tools.slice(0, 5).join(", ")}${cat.tools.length > 5 ? "..." : ""}`)
+        .join("\n");
+}
+/** The server instructions sent on initialize. Exported so the counts can be tested. */
+export function buildServerInstructions() {
+    const { tools, categories } = catalogCounts();
+    return `CBrowser — cognitive browser automation with ${tools} tools across ${categories} categories.
 
 CORE TOOLS (use these first):
 • navigate, click, fill, scroll, screenshot, extract — browser control
@@ -1149,17 +1192,7 @@ CORE TOOLS (use these first):
 • security_audit — MCP tool injection scanning
 
 SPECIALIST CATEGORIES (use when the task requires them):
-• visual_testing (9 tools) — visual_baseline, visual_regression, cross_browser_test, responsive_test, ab_comparison, transport_map, attention_analysis...
-• cognitive_transport (7 tools) — cognitive_distance, cognitive_coverage, cognitive_interpolate, cognitive_load_estimate, compare_personas...
-• testing (5 tools) — nl_test_inline, nl_test_file, detect_flaky_tests, coverage_map, repair_test
-• site_knowledge (5 tools) — site_model_status, site_model_query, site_profile_list/delete/status
-• bug_hunting (3 tools) — hunt_bugs, chaos_test, competitive_benchmark
-• performance (3 tools) — perf_baseline, perf_regression, list_baselines
-• sessions (4 tools) — save_session, load_session, list_sessions, delete_session
-• marketing (4 tools) — marketing_campaign_create/run/report, marketing_personas_list
-• persona_creation (6 tools) — persona_create_start, questionnaire, from_description
-• enterprise_security (8 tools) — web_security_scan, stealth_enable/disable/check, cloudflare_detect/wait
-• enterprise_marketing (6 tools) — marketing_influence_matrix, lever_analysis, funnel_analyze, audience_discover
+${specialistCategoryLines()}
 
 TIPS:
 • Pass _browserToken between tool calls to maintain browser state
@@ -1178,7 +1211,56 @@ SELF-HELP:
 • If you are unsure what a tool does, what a score means, which persona to use, or how tools work together — call question_answer with your question
 • question_answer searches 290+ pages of CBrowser documentation and returns a grounded answer
 • Use it before guessing. Example: question_answer(question: "What is the difference between viewport and full_page scope?")
-• Use it to explain results to the user. Example: question_answer(question: "What does a CTC of 1.6 with readability bottleneck mean?")`,
+• Use it to explain results to the user. Example: question_answer(question: "What does a CTC of 1.6 with readability bottleneck mean?")`;
+}
+/** Body of docs://tools-overview, counted from TOOL_CATEGORIES. */
+export function buildToolsOverviewText() {
+    const { tools, categories } = catalogCounts();
+    const list = TOOL_CATEGORIES.map((cat) => `${cat.name} (${cat.tools.length})`).join(", ");
+    return `CBrowser provides ${tools} MCP tools across ${categories} categories: ${list}. Visit https://cbrowser.ai/docs/Tools-Overview for the complete reference.`;
+}
+/** Body of docs://personas, listed from the persona maps themselves. */
+export function buildPersonasOverviewText() {
+    const groups = [
+        ["Cognitive", Object.keys(BUILTIN_PERSONAS)],
+        ["Accessibility", Object.keys(ACCESSIBILITY_PERSONAS)],
+        ["Emotional", Object.keys(EMOTIONAL_PERSONAS)],
+        ["AI agent", Object.keys(AGENT_PERSONAS)],
+    ];
+    const total = groups.reduce((n, [, names]) => n + names.length, 0);
+    const body = groups.map(([label, names]) => `${label} (${names.length}): ${names.join(", ")}`).join(". ");
+    return `CBrowser includes ${total} built-in personas: ${body}. Each human persona has 26 cognitive traits; agent personas describe AI agents with agent traits instead. Visit https://cbrowser.ai/docs/Persona-Index for details.`;
+}
+/** Number of built-in personas across every map docs://personas lists. */
+function builtinPersonaCount() {
+    return [BUILTIN_PERSONAS, ACCESSIBILITY_PERSONAS, EMOTIONAL_PERSONAS, AGENT_PERSONAS]
+        .reduce((n, map) => n + Object.keys(map).length, 0);
+}
+/**
+ * Create a configured MCP server instance
+ *
+ * @param customRegisterTools - Optional custom tool registration
+ * @param sessionId - Optional session ID for session isolation
+ */
+function createMcpServer(customRegisterTools, sessionId, resolvedTier) {
+    const server = new McpServer({
+        name: "cbrowser",
+        title: "CBrowser — Cognitive Browser Automation",
+        version: VERSION,
+        description: `AI-powered browser automation with cognitive user simulation. ${catalogCounts().tools} MCP tools for navigation, visual testing, accessibility auditing, persona-based testing, site knowledge learning, and security scanning. Simulates how real humans think, struggle, and give up on your site.`,
+        websiteUrl: "https://cbrowser.ai",
+        icons: [
+            { src: "https://cbrowser.ai/icon-192.png", sizes: ["192x192"] },
+            { src: "https://cbrowser.ai/icon-512.png", sizes: ["512x512"] },
+            { src: "https://cbrowser.ai/logo.svg", sizes: ["1080x1080"] },
+        ],
+    }, {
+        capabilities: {
+            tools: { listChanged: true },
+            prompts: {},
+            resources: {},
+        },
+        instructions: buildServerInstructions(),
     });
     // Register prompts for common workflows
     server.prompt("audit-site", "Run a comprehensive site audit with empathy, agent-readiness, and visual baseline", async () => ({
@@ -1210,17 +1292,17 @@ SELF-HELP:
     }));
     registerUiResources(server);
     // Register resources
-    server.resource("docs://tools-overview", "docs://tools-overview", { description: "Overview of all 105 CBrowser MCP tools organized by category", mimeType: "text/plain" }, async () => ({
+    server.resource("docs://tools-overview", "docs://tools-overview", { description: `Overview of all ${catalogCounts().tools} CBrowser MCP tools organized by category`, mimeType: "text/plain" }, async () => ({
         contents: [{
                 uri: "docs://tools-overview",
-                text: "CBrowser provides 120 MCP tools across 11 categories: Browser Automation, Visual Testing, Cognitive Journeys, Site Knowledge, Accessibility, Persona System, Testing, Performance, Security, Session Management, and Marketing. Visit https://cbrowser.ai/docs/Tools-Overview for the complete reference.",
+                text: buildToolsOverviewText(),
                 mimeType: "text/plain",
             }],
     }));
-    server.resource("docs://personas", "docs://personas", { description: "List of 21 built-in personas with cognitive traits", mimeType: "text/plain" }, async () => ({
+    server.resource("docs://personas", "docs://personas", { description: `List of ${builtinPersonaCount()} built-in personas`, mimeType: "text/plain" }, async () => ({
         contents: [{
                 uri: "docs://personas",
-                text: "CBrowser includes 21 personas: Cognitive (6): power-user, first-timer, mobile-user, elderly-user, impatient-user, screen-reader-user. Accessibility (11): motor-impairment-tremor, low-vision-magnified, cognitive-adhd, dyslexic-user, deaf-user, elderly-low-vision, color-blind-deuteranopia, autism-spectrum, intellectual-disability, aphasia-receptive, dyscalculia. Emotional (4): anxious-user, confident-user, emotional-user, stoic-user. Each persona has 26 cognitive traits. Visit https://cbrowser.ai/docs/Persona-Index for details.",
+                text: buildPersonasOverviewText(),
                 mimeType: "text/plain",
             }],
     }));
@@ -1370,11 +1452,7 @@ async function handleMcpRequest(req, res, transport) {
             }
             if (keyHash) {
                 const cmsUrl = process.env.CMS_URL || "http://localhost:3200";
-                const deductParams = new URLSearchParams({
-                    key_hash: keyHash,
-                    tool: toolName,
-                    ...(targetUrl ? { target_url: targetUrl } : {}),
-                });
+                const deductParams = deductQuery(keyHash, toolName, targetUrl);
                 try {
                     const creditRes = await fetch(`${cmsUrl}/api/credits/deduct?${deductParams}`, {
                         method: "POST",
@@ -1415,7 +1493,7 @@ async function handleMcpRequest(req, res, transport) {
                         // above either returned already (allowed:false) or are fail-open
                         // (a response with no `allowed` field at all, e.g. an internal-auth
                         // failure) — neither charged the account, so neither sets this.
-                        if (creditRes.ok && data.allowed === true) {
+                        if (chargedByDeduct(creditRes.ok, data)) {
                             chargedKeyHash = keyHash;
                             chargedTool = toolName;
                         }
@@ -1515,6 +1593,7 @@ async function handleMcpRequest(req, res, transport) {
  * @param options - Optional configuration including tool extension callback
  */
 export async function startRemoteMcpServer(options) {
+    setCreditChargeMode(options?.chargeCredits === false ? "none" : "charge");
     // Auto-initialize all data directories on server start
     ensureDirectories();
     // Session reaper + rate-limit sweeper. Started HERE rather than at module
@@ -1561,7 +1640,13 @@ export async function startRemoteMcpServer(options) {
         console.log(`  - Enterprise: unlimited`);
     }
     console.log(`Listening on ${host}:${port}`);
-    const httpServer = createServer(async (req, res) => {
+    // Every HTTP request runs in its own identity context, so the key hash, tier
+    // and API key the /mcp branch sets for it belong to it alone. They were module
+    // globals, set while the request's server was built and read when its tool
+    // ran, several awaits later; an overlapping request from another account
+    // overwrote them in between. The context starts as an unauthenticated caller
+    // at the deployment's default tier. (sec-identity, 2026-10-10)
+    const httpServer = createServer((req, res) => withRequestIdentity({ keyHash: null, tier: effectiveTier(null), apiKey: undefined }, async () => {
         const url = new URL(req.url || "/", `http://${req.headers.host}`);
         // Security headers (defense in depth)
         res.setHeader("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
@@ -1903,11 +1988,14 @@ if (urlParams.get('error')) {
         }
         // llms.txt - AI-readable documentation (WebMCP standard)
         if (url.pathname === "/llms.txt" || url.pathname === "/.well-known/llms.txt") {
+            // Count and category list derived from TOOL_CATEGORIES. The hand-written
+            // block said 91 tools, and its per-category numbers did not match the
+            // names it listed ("Visual Testing (6)" named five). (B33, 2026-10-10)
             res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
             res.end(`# CBrowser MCP Server
 # AI-powered browser automation with cognitive user simulation
 
-> CBrowser is an MCP server that provides 91 tools for browser automation,
+> CBrowser is an MCP server that provides ${catalogCounts().tools} tools for browser automation,
 > visual testing, cognitive user simulation, and accessibility auditing.
 > It simulates how real humans think, struggle, and give up on websites.
 
@@ -1930,17 +2018,8 @@ POST /mcp - Model Context Protocol endpoint (JSON-RPC 2.0 over SSE)
 - API Key authentication for programmatic access
 - Demo server (demo.cbrowser.ai): Rate-limited, no auth required
 
-## Tool Categories (91 tools)
-- Navigation (1): navigate
-- Interaction (5): click, smart_click, fill, scroll, press_key
-- Analysis (4): analyze_page, extract, find_element_by_intent, assert
-- Visual Testing (6): visual_baseline, visual_regression, cross_browser_test, responsive_test, ab_comparison
-- Cognitive (3): cognitive_journey_init, cognitive_journey_update_state, list_cognitive_personas
-- Personas (10): compare_personas_init, persona_create, persona_traits_list, etc.
-- Testing (5): nl_test_file, nl_test_inline, repair_test, detect_flaky_tests, coverage_map
-- Audit (4): agent_ready_audit, competitive_benchmark, empathy_audit, webmcp_ready_audit
-- Session (4): save_session, load_session, list_sessions, delete_session
-- Browser (4): browser_health, browser_recover, reset_browser, status
+## Tool Categories (${catalogCounts().tools} tools)
+${TOOL_CATEGORIES.map((cat) => `- ${cat.name} (${cat.tools.length}): ${cat.tools.join(", ")}`).join("\n")}
 
 ## Links
 - Documentation: https://cbrowser.ai/docs
@@ -1987,8 +2066,8 @@ ${VERSION}
   }
 }</code></pre>
 
-  <h2>Available Tools (91)</h2>
-  <p>This server provides 91 MCP tools for browser automation, testing, and analysis.</p>
+  <h2>Available Tools (${catalogCounts().tools})</h2>
+  <p>This server provides ${catalogCounts().tools} MCP tools for browser automation, testing, and analysis.</p>
   <ul>
     <li><strong>Navigation:</strong> navigate, screenshot</li>
     <li><strong>Interaction:</strong> click, smart_click, fill, scroll, press_key</li>
@@ -2253,6 +2332,21 @@ ${VERSION}
             // Log session handling for debugging (truncate ID for readability)
             const shortId = browserSessionId.substring(0, 8);
             console.log(`[Session] ${sessionSource}: ${shortId}... (active: ${activeSessions.size})`);
+            // This request's caller, written into its own identity context (entered at
+            // createServer above). Set before the transport branch so a reused
+            // stateful transport gets it too: that path used to run on whatever the
+            // last request to build a server had left in the globals. Building a new
+            // server below sets the tier again during registration, as it always did.
+            // (sec-identity, 2026-10-10)
+            const requestApiKey = extractApiKey(req);
+            const resolvedTier = requestApiKey ? await resolveApiKeyTier(requestApiKey) : null;
+            // Key hash for usage tracking: a cbk_ key's own hash, or the key an OAuth
+            // token was issued for; null otherwise. The same derivation as billing.
+            setActiveKeyHash(await resolveRequestKeyHash(req));
+            // Raw key for account-scoped features (custom personas, etc.)
+            const { setSessionApiKey } = await import("./mcp-tools/base/cognitive-tools.js");
+            setSessionApiKey(requestApiKey || undefined);
+            setTierGate(effectiveTier(resolvedTier));
             // Now handle transport (stateful mode caches transport, stateless creates new each time)
             const hasExistingTransport = existingSessionId ? transports.has(existingSessionId) : false;
             if (sessionMode === "stateful" && existingSessionId && hasExistingTransport) {
@@ -2266,30 +2360,6 @@ ${VERSION}
                 transport = new StreamableHTTPServerTransport({
                     sessionIdGenerator: sessionMode === "stateful" ? () => browserSessionId : undefined,
                 });
-                // Resolve pricing tier from API key (cbk_ keys → CMS lookup)
-                const requestApiKey = extractApiKey(req);
-                const resolvedTier = requestApiKey ? await resolveApiKeyTier(requestApiKey) : null;
-                // Set key hash for usage tracking
-                if (requestApiKey?.startsWith("cbk_")) {
-                    const { createHash } = await import("crypto");
-                    setActiveKeyHash(createHash("sha256").update(requestApiKey).digest("hex"));
-                }
-                else if (requestApiKey) {
-                    // Check token→keyHash map (OAuth tokens that aren't raw cbk_ keys)
-                    const mapped = tokenToKeyHash.get(requestApiKey);
-                    if (mapped && mapped.expiresAt > Date.now()) {
-                        setActiveKeyHash(mapped.keyHash);
-                    }
-                    else {
-                        setActiveKeyHash(null);
-                    }
-                }
-                else {
-                    setActiveKeyHash(null);
-                }
-                // Set session API key for account-scoped features (custom personas, etc.)
-                const { setSessionApiKey } = await import("./mcp-tools/base/cognitive-tools.js");
-                setSessionApiKey(requestApiKey || undefined);
                 // Create and connect server with session isolation and tier gating
                 const server = createMcpServer(options?.registerTools, browserSessionId, resolvedTier);
                 // Allow extension with additional tools (for Enterprise)
@@ -2347,7 +2417,7 @@ ${VERSION}
         // 404 for other paths
         res.writeHead(404, { "Content-Type": "application/json" });
         res.end(JSON.stringify({ error: "Not found" }));
-    });
+    }));
     httpServer.listen(port, host, () => {
         void (async () => {
             console.log(`\nCognitive Browser Remote MCP Server running at http://${host}:${port}`);