@mehmoodqureshi/chrome-mcp 0.6.5 → 0.6.6

package/dist/src/executor/stub-executor.d.ts

@@ -23,6 +23,15 @@ export interface StubOptions {
     /** A URL the backend claims to already know, as the extension reports on every
      *  result frame. Set it to assert the gate uses it INSTEAD of calling tabsList. */
     cachedUrl?: string;
+    /** Background (non-active) tabs, so a test can target one by an explicit tabId
+     *  and check the gate authorizes against THAT tab rather than the active one. */
+    backgroundTabs?: Array<{
+        tabId: TabId;
+        url: string;
+    }>;
+    /** When true, tabs exist but none is flagged active — the case the gate used to
+     *  paper over by silently gating against `tabs[0]`. */
+    noActiveTab?: boolean;
 }
 export declare class StubExecutor implements Executor {
     readonly backend: BackendKind;
@@ -32,6 +41,8 @@ export declare class StubExecutor implements Executor {
     private readonly noTabs;
     private readonly blankTabUrl;
     private readonly cached;
+    private readonly backgroundTabs;
+    private readonly noActiveTab;
     /** How many times the gate actually asked for the tab list — the round-trip
      *  counter the caching path exists to keep at zero. */
     tabsListCalls: number;

package/dist/src/executor/stub-executor.js

@@ -22,6 +22,8 @@ class StubExecutor {
     noTabs;
     blankTabUrl;
     cached;
+    backgroundTabs;
+    noActiveTab;
     /** How many times the gate actually asked for the tab list — the round-trip
      *  counter the caching path exists to keep at zero. */
     tabsListCalls = 0;
@@ -33,13 +35,15 @@ class StubExecutor {
         this.noTabs = opts.noTabs ?? false;
         this.blankTabUrl = opts.blankTabUrl ?? false;
         this.cached = opts.cachedUrl ?? null;
+        this.backgroundTabs = opts.backgroundTabs ?? [];
+        this.noActiveTab = opts.noActiveTab ?? false;
     }
     tab() {
         return {
             tabId: 'extension:stub:1',
             url: this.blankTabUrl ? '' : this.url,
             title: 'Stub Page',
-            active: true,
+            active: !this.noActiveTab,
             index: 0,
         };
     }
@@ -68,7 +72,18 @@ class StubExecutor {
         this.tabsListCalls++;
         if (this.tabsListThrows)
             throw new types_1.ExecutorError('EXTENSION_DISCONNECTED', 'stub bridge is down');
-        return this.noTabs ? [] : [this.tab()];
+        if (this.noTabs)
+            return [];
+        return [
+            this.tab(),
+            ...this.backgroundTabs.map((t, i) => ({
+                tabId: t.tabId,
+                url: t.url,
+                title: 'Stub Background Page',
+                active: false,
+                index: i + 1,
+            })),
+        ];
     }
     async tabSelect(tabId) {
         return { ...this.tab(), tabId };

package/dist/src/mcp/tools.js

@@ -81,24 +81,34 @@ exports.TOOL_DEFINITIONS = [
         },
     },
 ];
-const GATE_CONTEXT = 'cannot resolve the active tab URL for the policy gate';
+const GATE_CONTEXT = 'cannot resolve the target tab URL for the policy gate';
 /**
- * Resolve the URL the policy should be evaluated against (the active tab).
+ * Resolve the URL the policy should be evaluated against: the URL of the tab
+ * this very call will act on — the explicit `tabId` when the caller gave one,
+ * the active tab only when they didn't.
  *
- * NEVER substitutes a placeholder URL. If the tab list can't be read, the real
- * origin is unknown, and evaluating the policy against a fabricated URL would
- * silently allow or deny against the wrong origin with no signal to the caller.
- * So a `tabsList` failure (or a browser reporting no tabs at all) propagates —
- * the dispatch firewall renders it as a structured error carrying the code.
+ * Gating on the ACTIVE tab regardless of `tabId` is an authorization bypass:
+ * park an allowlisted page as active and every `tabId`-addressed read (get_text,
+ * get_html, screenshot, eval, …) sails through against a tab whose origin was
+ * never checked. The tab that gets touched is the tab that must be authorized.
+ *
+ * NEVER substitutes a placeholder URL, and never falls back to some *other*
+ * tab. If the real origin is unknown, evaluating the policy against a stand-in
+ * would silently allow or deny against the wrong origin with no signal to the
+ * caller. So a `tabsList` failure (or a browser reporting no tabs at all)
+ * propagates — the dispatch firewall renders it as an error carrying the code.
  *
  * Prefers a URL the backend already reported over asking again: the extension
  * rides the tab's landing URL home on every result frame, which is what keeps a
- * gated call to ONE round-trip instead of two.
+ * gated call to ONE round-trip instead of two. That cache only ever describes
+ * the active tab, so it is bypassed whenever an explicit `tabId` is in play.
  */
-async function activeUrl(ex) {
-    const known = ex.cachedActiveUrl?.();
-    if (known)
-        return known;
+async function gatedUrl(ex, tabId) {
+    if (!tabId) {
+        const known = ex.cachedActiveUrl?.();
+        if (known)
+            return known;
+    }
     let tabs;
     try {
         tabs = await ex.tabsList();
@@ -111,30 +121,39 @@ async function activeUrl(ex) {
             throw new types_1.ExecutorError(err.code, `${GATE_CONTEXT}: ${err.message}`);
         throw err; // an internal fault, not a browser one — don't relabel it
     }
-    const active = tabs.find((t) => t.active) ?? tabs[0];
-    if (!active)
+    if (tabs.length === 0) {
         throw new types_1.ExecutorError('TAB_NOT_FOUND', `${GATE_CONTEXT}: the browser reports no open tabs`);
+    }
+    const target = tabId ? tabs.find((t) => t.tabId === tabId) : tabs.find((t) => t.active);
+    if (!target) {
+        throw new types_1.ExecutorError('TAB_NOT_FOUND', tabId
+            ? `${GATE_CONTEXT}: no open tab has id ${tabId} — call tabs_list for the current ids`
+            : `${GATE_CONTEXT}: the browser reports open tabs but none active — pass an explicit tabId`);
+    }
     // An empty URL is Chrome declining to reveal one (a chrome:// page, or a tab
     // the extension has no host access to) — NOT an origin. Gating on '' would
     // produce a baffling "blocked on " denial that reads like a policy decision.
-    if (!active.url) {
-        throw new types_1.ExecutorError('TAB_NOT_FOUND', `${GATE_CONTEXT}: the active tab (id ${active.tabId}) reports no URL. Chrome hides it for ` +
+    if (!target.url) {
+        throw new types_1.ExecutorError('TAB_NOT_FOUND', `${GATE_CONTEXT}: the target tab (id ${target.tabId}) reports no URL. Chrome hides it for ` +
             `internal pages (chrome://, the Web Store) and until the extension has access to that site — ` +
             `switch to a normal page, or open the target site in a new tab.`);
     }
-    return active.url;
+    return target.url;
 }
 /**
- * Policy chokepoint. `urlOverride` is the destination for navigation.
+ * Policy chokepoint. `opts.url` is the destination for navigation (it governs
+ * instead of any current tab URL); `opts.tabId` is the tab the call will act on,
+ * and MUST be threaded through by every URL-gated handler that accepts one —
+ * omitting it silently authorizes the call against the active tab instead.
  *
- * Only resolves the active URL for methods whose verdict actually depends on one
+ * Only resolves a tab URL for methods whose verdict actually depends on one
  * (`isUrlGated`). Tab management and the capability gates — eval, downloads,
  * uploads, mutations — are decided without any URL, so making them wait on the
  * tab list bought nothing and, worse, made `tab_new` fail exactly when the tab
  * list was unreadable: the one call that could dig you out.
  */
-async function gate(ctx, method, urlOverride) {
-    const url = urlOverride ?? ((0, policy_1.isUrlGated)(method) ? await activeUrl(ctx.ex) : '');
+async function gate(ctx, method, opts = {}) {
+    const url = opts.url ?? ((0, policy_1.isUrlGated)(method) ? await gatedUrl(ctx.ex, opts.tabId) : '');
     (0, policy_1.assertUrlAllowed)(url, method, ctx.policy);
 }
 const tabId = (args) => (0, validators_1.optionalString)(args, 'tabId');
@@ -180,24 +199,24 @@ exports.TOOL_HANDLERS = {
     },
     navigate: async (a, ctx) => {
         const url = (0, validators_1.requireString)(a, 'url');
-        await gate(ctx, 'navigate', url);
+        await gate(ctx, 'navigate', { url });
         return (0, envelopes_1.jsonResult)(await ctx.ex.navigate({ url, tabId: tabId(a), waitUntil: waitUntil(a) }));
     },
     back: async (a, ctx) => {
-        await gate(ctx, 'back');
+        await gate(ctx, 'back', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.back(tabId(a)));
     },
     forward: async (a, ctx) => {
-        await gate(ctx, 'forward');
+        await gate(ctx, 'forward', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.forward(tabId(a)));
     },
     reload: async (a, ctx) => {
-        await gate(ctx, 'reload');
+        await gate(ctx, 'reload', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.reload({ tabId: tabId(a), waitUntil: waitUntil(a) }));
     },
     click: async (a, ctx) => {
         const t = (0, validators_1.requireTarget)(a);
-        await gate(ctx, 'click');
+        await gate(ctx, 'click', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.click(t, {
             tabId: tabId(a),
             button: (0, validators_1.optionalString)(a, 'button'),
@@ -207,7 +226,7 @@ exports.TOOL_HANDLERS = {
     },
     type: async (a, ctx) => {
         const t = (0, validators_1.requireTarget)(a);
-        await gate(ctx, 'type');
+        await gate(ctx, 'type', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.type(t, (0, validators_1.requireWithinLength)((0, validators_1.requireString)(a, 'text'), 'text', validators_1.MAX_TEXT_LEN), {
             tabId: tabId(a),
             clear: (0, validators_1.optionalBoolean)(a, 'clear'),
@@ -218,14 +237,14 @@ exports.TOOL_HANDLERS = {
     },
     select_option: async (a, ctx) => {
         const t = (0, validators_1.requireTarget)(a);
-        await gate(ctx, 'type'); // mutating
+        await gate(ctx, 'type', { tabId: tabId(a) }); // mutating
         const values = (0, validators_1.optionalStringArray)(a, 'values');
         if (!values || values.length === 0)
             throw new validators_1.McpToolError('"values" must be a non-empty array of strings');
         return (0, envelopes_1.jsonResult)(await ctx.ex.selectOption(t, values, { tabId: tabId(a) }));
     },
     press: async (a, ctx) => {
-        await gate(ctx, 'press');
+        await gate(ctx, 'press', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.press((0, validators_1.requireString)(a, 'key'), {
             tabId: tabId(a),
             modifiers: (0, validators_1.optionalStringArray)(a, 'modifiers'),
@@ -233,11 +252,11 @@ exports.TOOL_HANDLERS = {
     },
     hover: async (a, ctx) => {
         const t = (0, validators_1.requireTarget)(a);
-        await gate(ctx, 'hover');
+        await gate(ctx, 'hover', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.hover(t, { tabId: tabId(a) }));
     },
     scroll: async (a, ctx) => {
-        await gate(ctx, 'scroll');
+        await gate(ctx, 'scroll', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.scroll({
             tabId: tabId(a),
             x: (0, validators_1.optionalNumber)(a, 'x'),
@@ -248,7 +267,7 @@ exports.TOOL_HANDLERS = {
         }));
     },
     screenshot: async (a, ctx) => {
-        await gate(ctx, 'screenshot');
+        await gate(ctx, 'screenshot', { tabId: tabId(a) });
         const shot = await ctx.ex.screenshot({
             tabId: tabId(a),
             fullPage: (0, validators_1.optionalBoolean)(a, 'fullPage'),
@@ -259,17 +278,17 @@ exports.TOOL_HANDLERS = {
         return (0, envelopes_1.imageResult)(shot.dataBase64, shot.mimeType, caption);
     },
     get_text: async (a, ctx) => {
-        await gate(ctx, 'get_text');
+        await gate(ctx, 'get_text', { tabId: tabId(a) });
         const res = await ctx.ex.getText((0, validators_1.optionalTarget)(a), { tabId: tabId(a) });
         (0, workspace_1.saveResult)('get_text', 'json', JSON.stringify(res, null, 2));
         return (0, envelopes_1.jsonResult)(res);
     },
     get_html: async (a, ctx) => {
-        await gate(ctx, 'get_html');
+        await gate(ctx, 'get_html', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.getHtml((0, validators_1.optionalTarget)(a), { tabId: tabId(a), outer: (0, validators_1.optionalBoolean)(a, 'outer') }));
     },
     snapshot: async (a, ctx) => {
-        await gate(ctx, 'get_text'); // read of page structure
+        await gate(ctx, 'get_text', { tabId: tabId(a) }); // read of page structure
         return (0, envelopes_1.jsonResult)(await ctx.ex.snapshot({
             tabId: tabId(a),
             interactiveOnly: (0, validators_1.optionalBoolean)(a, 'interactiveOnly'),
@@ -277,13 +296,13 @@ exports.TOOL_HANDLERS = {
         }));
     },
     get_cookies: async (a, ctx) => {
-        await gate(ctx, 'get_text'); // reads tab-scoped secrets; same domain gate as content reads
+        await gate(ctx, 'get_text', { tabId: tabId(a) }); // reads tab-scoped secrets; same domain gate as content reads
         return (0, envelopes_1.jsonResult)(await ctx.ex.getCookies({ tabId: tabId(a), url: (0, validators_1.optionalString)(a, 'url') }));
     },
     storage: async (a, ctx) => {
         const op = (0, validators_1.requireString)(a, 'op');
         // get is a read; set/remove/clear mutate.
-        await gate(ctx, op === 'get' ? 'get_text' : 'type');
+        await gate(ctx, op === 'get' ? 'get_text' : 'type', { tabId: tabId(a) });
         if ((op === 'set' || op === 'remove') && !(0, validators_1.optionalString)(a, 'key')) {
             throw new validators_1.McpToolError(`storage "${op}" requires a "key"`);
         }
@@ -296,14 +315,14 @@ exports.TOOL_HANDLERS = {
         }));
     },
     eval: async (a, ctx) => {
-        await gate(ctx, 'eval');
+        await gate(ctx, 'eval', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.eval((0, validators_1.requireString)(a, 'expression'), {
             tabId: tabId(a),
             awaitPromise: (0, validators_1.optionalBoolean)(a, 'awaitPromise'),
         }));
     },
     wait_for: async (a, ctx) => {
-        await gate(ctx, 'wait_for');
+        await gate(ctx, 'wait_for', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.waitFor({
             tabId: tabId(a),
             selector: (0, validators_1.optionalString)(a, 'selector'),
@@ -313,7 +332,7 @@ exports.TOOL_HANDLERS = {
         }));
     },
     extract_links: async (a, ctx) => {
-        await gate(ctx, 'get_text'); // read of page content
+        await gate(ctx, 'get_text', { tabId: tabId(a) }); // read of page content
         const res = await (0, helpers_1.extractLinks)(ctx.ex, {
             selector: (0, validators_1.optionalString)(a, 'selector'),
             sameOriginOnly: (0, validators_1.optionalBoolean)(a, 'sameOriginOnly'),
@@ -325,13 +344,13 @@ exports.TOOL_HANDLERS = {
         return (0, envelopes_1.jsonResult)(res);
     },
     read_as_markdown: async (a, ctx) => {
-        await gate(ctx, 'get_text');
+        await gate(ctx, 'get_text', { tabId: tabId(a) });
         const md = await (0, helpers_1.readAsMarkdown)(ctx.ex, { selector: (0, validators_1.optionalString)(a, 'selector'), tabId: tabId(a) });
         (0, workspace_1.saveResult)('read_as_markdown', 'md', md);
         return (0, envelopes_1.textResult)(md);
     },
     fill_form: async (a, ctx) => {
-        await gate(ctx, 'type'); // mutating
+        await gate(ctx, 'type', { tabId: tabId(a) }); // mutating
         const fields = a.fields;
         if (typeof fields !== 'object' || fields === null || Array.isArray(fields)) {
             throw new validators_1.McpToolError('"fields" must be an object mapping selector -> string|boolean');
@@ -356,7 +375,7 @@ exports.TOOL_HANDLERS = {
     },
     upload_file: async (a, ctx) => {
         const t = (0, validators_1.requireTarget)(a);
-        await gate(ctx, 'upload_file');
+        await gate(ctx, 'upload_file', { tabId: tabId(a) });
         const files = (0, validators_1.optionalStringArray)(a, 'files');
         if (!files || files.length === 0)
             throw new validators_1.McpToolError('"files" must be a non-empty array of absolute local paths');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehmoodqureshi/chrome-mcp",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "Drive your real Chrome browser over MCP — real logins, real cookies. A stdio MCP server (CLI) plus an MV3 extension, driving Chrome via chrome.scripting/chrome.tabs. Multi-tab batch automation, accessibility snapshots, deny-all security by default.",
   "author": "Mehmood Ur Rehman Qureshi",
   "license": "MIT",