diff --git a/CHANGELOG.md b/CHANGELOG.md index 76353c59..7b9be9e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,13 @@ info and the tab list carry the same fields. Screenshot, storage, console, network, and audits on those pages return that result instead of an empty success. +- **Tab awareness without the debugging banner.** `listTabs`, `readTab`, + `navigateTab`, `softClick`, and `softType` use `chrome.tabs` and + `chrome.scripting`. They do not attach the debugger and do not change focus. + `chromeTabId` from `listTabs` is separate from the DevTools-connected `tabId` + used by `listBrowserTabs`. The tab list does not claim to see every open tab. + Background navigation stays in the visible window. Soft click and type report + `worked` or `needs a real gesture`. ## 2.0.5 diff --git a/README.md b/README.md index 03755f74..6160e276 100644 --- a/README.md +++ b/README.md @@ -98,7 +98,12 @@ setup and a silent one look the same. | `getSelectedElement` | The element selected in the Elements panel | | `getPageInfo` | Which page the browser is currently on | | `getConnectionStatus` | Whether the extension is connected, and capture counts | -| `listBrowserTabs` | Every tab with DevTools open, and the id to address it by | +| `listBrowserTabs` | Tabs with DevTools open, addressed by a DevTools-connected `tabId` | +| `listTabs` | Tabs `chrome.tabs` returns (not every open tab), addressed by `chromeTabId` | +| `readTab` | Headings, excerpt, and a snapshot of a `chromeTabId`, without the debugger | +| `navigateBrowser` | Load a URL in a DevTools-connected tab, without focusing it | +| `navigateTab` | Load a URL in the background from `listTabs`, visible window only | +| `softClick` / `softType` | Untrusted click or type. Result is `worked` or `needs a real gesture` | | `takeScreenshot` | Screenshot returned **as an image**, plus its file path | | `refreshBrowser` | Reloads the inspected tab | | `getBrowserStorage` | localStorage, sessionStorage and cookies (values gated) | @@ -116,6 +121,16 @@ All tools declare MCP output schemas, so clients receive structured data rather than prose they have to parse, and read-only tools are annotated as such so clients can auto-approve them safely. +### Tabs without DevTools + +`listTabs`, `readTab`, `navigateTab`, `softClick`, and `softType` use `chrome.tabs` and `chrome.scripting`. They do not attach the debugger, so they do not show the debugging banner, and they do not activate a tab or focus a window. + +`chromeTabId` comes from `listTabs`. `tabId` on the other tools comes from `listBrowserTabs`. They are different id spaces. Pass each id only to the tool that issued it. + +`listTabs` reports the tabs `chrome.tabs` returns in the windows it returns. Other Arc Spaces, Little Arc, pinned favorites, split-view partners, and slept tabs may be missing. Incognito is skipped. This is not every open tab. Background navigation stays in the visible window until that is measured on Arc. + +The popup switch has to be on. Navigation and soft input also need `--allow-input` on `browser-tools-mcp`, or `--allow-actions` on the `browser-tools` CLI. The same origin rules as other input apply. An asleep tab is reported and not reloaded. A soft action says `worked` or `needs a real gesture` and does not claim a failed action worked. + ### Several tabs at once Every tab with DevTools open is tracked separately. Telemetry is attributed to diff --git a/SECURITY.md b/SECURITY.md index 64757b29..6c8ea2b0 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -127,8 +127,11 @@ be, both are worth reporting. - Chrome's "started debugging this browser" banner is a browser safety control. It is intentional, and this project never hides it, suppresses it, or documents a setup step that does. Features that can run without the - debugger do so. When a feature attaches the debugger, the banner stays - visible for that attachment, and dismissing it stops the attachment. + debugger do so. `listTabs`, `readTab`, `navigateTab`, `softClick`, and + `softType` use ordinary extension APIs and do not call `chrome.debugger`, + `tabs.update({active:true})`, or `windows.update({focused:true})`. When a + feature attaches the debugger, the banner stays visible for that attachment, + and dismissing it stops the attachment. - Credential-bearing headers and secret-shaped strings are redacted before storage, not before display. - Request bodies are size-limited; log retention is bounded and client-supplied diff --git a/browser-tools-mcp/src/connector/api-policy.ts b/browser-tools-mcp/src/connector/api-policy.ts index 83137184..2f44182e 100644 --- a/browser-tools-mcp/src/connector/api-policy.ts +++ b/browser-tools-mcp/src/connector/api-policy.ts @@ -34,6 +34,11 @@ const AUDIT_TOOL: Record = { * a unit test, so a new tool cannot skip the filter by accident. */ export const API_TOOL_NAMES: readonly string[] = [ + "listTabs", + "readTab", + "navigateTab", + "softClick", + "softType", "listBrowserTabs", "getConsoleLogs", "getConsoleErrors", @@ -97,6 +102,11 @@ function toolsForRequest(method: string, path: string, query: Record; + /** Tabs chrome.tabs returns. Not the DevTools-connected list from listTabs(). */ + listChromeTabs(): Promise; + readChromeTab(options: { chromeTabId: number }): Promise; + /** Background navigate by chrome.tabs id, or a new background tab when chromeTabId is omitted. */ + navigateChromeTab(options: { url: string; chromeTabId?: number }): Promise; + softClickChromeTab(options: { chromeTabId: number; selector: string }): Promise; + softTypeChromeTab(options: { + chromeTabId: number; + selector: string; + text: string; + submit?: boolean; + }): Promise; close(): Promise; } @@ -267,6 +292,7 @@ export interface CapabilityCheck { action: string; reason: string; liveUrl: string | null; + excludeOrigins: string[]; } interface ExtensionConnection { @@ -575,6 +601,82 @@ export async function createConnector(config: ConnectorConfig = {}): Promise { + try { + res.json(await listChromeTabs()); + } catch (error) { + respondWithError(res, error); + } + }); + + api.post("/chrome-tabs/read", async (req: Request, res: Response) => { + try { + const chromeTabId = req.body?.chromeTabId; + if (typeof chromeTabId !== "number") { + res.status(400).json({ error: "chromeTabId is required" }); + return; + } + res.json(await readChromeTab({ chromeTabId })); + } catch (error) { + respondWithError(res, error); + } + }); + + api.post("/chrome-tabs/navigate", async (req: Request, res: Response) => { + try { + const url = typeof req.body?.url === "string" ? req.body.url.trim() : ""; + if (!url) { + res.status(400).json({ error: "url is required" }); + return; + } + const chromeTabId = req.body?.chromeTabId; + res.json( + await navigateChromeTab({ + url, + ...(typeof chromeTabId === "number" ? { chromeTabId } : {}), + }) + ); + } catch (error) { + respondWithError(res, error); + } + }); + + api.post("/chrome-tabs/soft-click", async (req: Request, res: Response) => { + try { + const chromeTabId = req.body?.chromeTabId; + const selector = req.body?.selector; + if (typeof chromeTabId !== "number" || typeof selector !== "string") { + res.status(400).json({ error: "chromeTabId and selector are required" }); + return; + } + res.json(await softClickChromeTab({ chromeTabId, selector })); + } catch (error) { + respondWithError(res, error); + } + }); + + api.post("/chrome-tabs/soft-type", async (req: Request, res: Response) => { + try { + const chromeTabId = req.body?.chromeTabId; + const selector = req.body?.selector; + const text = req.body?.text; + if (typeof chromeTabId !== "number" || typeof selector !== "string" || typeof text !== "string") { + res.status(400).json({ error: "chromeTabId, selector, and text are required" }); + return; + } + res.json( + await softTypeChromeTab({ + chromeTabId, + selector, + text, + submit: req.body?.submit === true, + }) + ); + } catch (error) { + respondWithError(res, error); + } + }); + api.post("/navigate", async (req: Request, res: Response) => { try { const url = typeof req.body?.url === "string" ? req.body.url.trim() : ""; @@ -1048,6 +1150,16 @@ export async function createConnector(config: ConnectorConfig = {}): Promise connection.role === "worker" && connection.fromExtension && connection.ws.readyState === WebSocket.OPEN ); + workers.sort((a, b) => b.lastSeen - a.lastSeen); + return workers[0]; } function denyCheck(action: string, reason: string): CapabilityCheck { - return { allowed: false, action, reason, liveUrl: null }; + return { + allowed: false, + action, + reason, + liveUrl: null, + excludeOrigins: capabilityPolicy.excludeOrigins, + }; } async function checkCapability( action: CapabilityAction, - options: { tabId?: TabId; destinationUrl?: string; hideBanner?: boolean } = {} + options: { tabId?: TabId; destinationUrl?: string; hideBanner?: boolean; creatingTab?: boolean } = {} ): Promise { if (options.hideBanner === true) return denyCheck(action, GateReason.banner); if (excludeListInvalid) return denyCheck(action, GateReason.excludeInvalid); @@ -1598,18 +1722,103 @@ export async function createConnector(config: ConnectorConfig = {}): Promise { + const gate = await checkCapability("listTabs"); + if (!gate.allowed) throw new ExtensionRequestError(gate.reason); + const response = await requestFromExtension(requireWorker(), "list-chrome-tabs", {}); + assertTabActionSafe(response); + return normalizeChromeTabListing(response, { ...capabilityPolicy, excludeOrigins: gate.excludeOrigins }); + } + + async function readChromeTab(options: { chromeTabId: number }): Promise { + const gate = await checkCapability("readTab", { tabId: options.chromeTabId }); + if (!gate.allowed) throw new ExtensionRequestError(gate.reason); + const response = await requestFromExtension(requireWorker(), "read-chrome-tab", { + chromeTabId: options.chromeTabId, + approvedUrl: gate.liveUrl, }); + assertTabActionSafe(response); + return parseChromeTabRead(options.chromeTabId, response["read"]); + } - return { allowed: decision.allowed, action, reason: decision.reason, liveUrl }; + async function navigateChromeTab(options: { + url: string; + chromeTabId?: number; + }): Promise { + const requestedUrl = parseHttpUrl(options.url.trim()).href; + const creating = options.chromeTabId == null; + const gate = await checkCapability("navigate", { + destinationUrl: requestedUrl, + ...(creating ? { creatingTab: true } : { tabId: options.chromeTabId }), + }); + if (!gate.allowed) throw new ExtensionRequestError(gate.reason); + const response = await requestFromExtension(requireWorker(), "navigate-chrome-tab", { + url: requestedUrl, + ...(creating + ? { create: true } + : { chromeTabId: options.chromeTabId, approvedUrl: gate.liveUrl }), + }); + return parseChromeNavigate(requestedUrl, response); + } + + async function softClickChromeTab(options: { + chromeTabId: number; + selector: string; + }): Promise { + return softInput("softClick", options); + } + + async function softTypeChromeTab(options: { + chromeTabId: number; + selector: string; + text: string; + submit?: boolean; + }): Promise { + return softInput("softType", options); + } + + async function softInput( + action: "softClick" | "softType", + options: { chromeTabId: number; selector: string; text?: string; submit?: boolean } + ): Promise { + const gate = await checkCapability(action, { tabId: options.chromeTabId }); + if (!gate.allowed) throw new ExtensionRequestError(gate.reason); + const response = await requestFromExtension(requireWorker(), "soft-input", { + op: action === "softType" ? "type" : "click", + chromeTabId: options.chromeTabId, + selector: options.selector, + approvedUrl: gate.liveUrl, + ...(action === "softType" ? { text: options.text ?? "", submit: options.submit === true } : {}), + }); + return parseSoftInput(options.chromeTabId, response); } async function close(): Promise { @@ -1661,6 +1870,11 @@ export async function createConnector(config: ConnectorConfig = {}): Promise; refresh(options?: { tabId?: TabId }): Promise; navigate(options: { url: string; tabId?: TabId }): Promise; + listChromeTabs(): Promise; + readChromeTab(options: { chromeTabId: number }): Promise; + navigateChromeTab(options: { url: string; chromeTabId?: number }): Promise; + softClickChromeTab(options: { chromeTabId: number; selector: string }): Promise; + softTypeChromeTab(options: { + chromeTabId: number; + selector: string; + text: string; + submit?: boolean; + }): Promise; storage(kinds: string[], options?: { tabId?: TabId }): Promise>; audit( category: AuditCategory, @@ -172,6 +188,31 @@ export class InProcessConnectorClient implements ConnectorClient { return this.#connector.navigateTab(options); } + listChromeTabs(): Promise { + return this.#connector.listChromeTabs(); + } + + readChromeTab(options: { chromeTabId: number }): Promise { + return this.#connector.readChromeTab(options); + } + + navigateChromeTab(options: { url: string; chromeTabId?: number }): Promise { + return this.#connector.navigateChromeTab(options); + } + + softClickChromeTab(options: { chromeTabId: number; selector: string }): Promise { + return this.#connector.softClickChromeTab(options); + } + + softTypeChromeTab(options: { + chromeTabId: number; + selector: string; + text: string; + submit?: boolean; + }): Promise { + return this.#connector.softTypeChromeTab(options); + } + async storage( kinds: string[], options: { tabId?: TabId } = {} @@ -300,6 +341,31 @@ export class HttpConnectorClient implements ConnectorClient { return this.#request("/api/navigate", { method: "POST", body: options }); } + listChromeTabs(): Promise { + return this.#request("/api/chrome-tabs"); + } + + readChromeTab(options: { chromeTabId: number }): Promise { + return this.#request("/api/chrome-tabs/read", { method: "POST", body: options }); + } + + navigateChromeTab(options: { url: string; chromeTabId?: number }): Promise { + return this.#request("/api/chrome-tabs/navigate", { method: "POST", body: options }); + } + + softClickChromeTab(options: { chromeTabId: number; selector: string }): Promise { + return this.#request("/api/chrome-tabs/soft-click", { method: "POST", body: options }); + } + + softTypeChromeTab(options: { + chromeTabId: number; + selector: string; + text: string; + submit?: boolean; + }): Promise { + return this.#request("/api/chrome-tabs/soft-type", { method: "POST", body: options }); + } + async storage( kinds: string[], options: { tabId?: TabId } = {} diff --git a/browser-tools-mcp/src/mcp/server.ts b/browser-tools-mcp/src/mcp/server.ts index 35ac4ee2..16a9c4dd 100644 --- a/browser-tools-mcp/src/mcp/server.ts +++ b/browser-tools-mcp/src/mcp/server.ts @@ -20,6 +20,13 @@ import { RestrictedPageError, restrictedPageToolText, } from "../restricted-page.js"; +import { + DEVTOOLS_TAB_ID, + DEVTOOLS_TAB_INPUT, + LIST_BROWSER_TABS_DESCRIPTION, + NAVIGATE_BROWSER_DESCRIPTION, +} from "../tabs/contract.js"; +import { TAB_TOOLS } from "../tabs/tools.js"; const log = createLogger("mcp"); @@ -144,7 +151,9 @@ const queryOutputShape = { tabId: z .union([z.number(), z.string()]) .nullable() - .describe("The tab these entries came from, or null when reading every tab"), + .describe( + "DevTools-connected tab id these entries came from, or null when reading every connected tab. Not a chromeTabId from listTabs." + ), url: z.string().describe("The page that tab is on"), otherTabs: z .number() @@ -160,11 +169,7 @@ const queryOutputShape = { const tabIdInput = z .union([z.number().int(), z.string()]) .optional() - .describe( - "Which browser tab to use, from listBrowserTabs. Omit to use the current tab — the " + - "one DevTools was most recently opened on, which is right in almost every session. " + - "Only pass this when a result reported otherTabs above 0 and you need a specific tab." - ); + .describe(DEVTOOLS_TAB_INPUT); const allTabsInput = z .boolean() @@ -264,26 +269,22 @@ function auditTool( } const TOOLS: ToolDefinition[] = [ + ...TAB_TOOLS, { name: "listBrowserTabs", register(server, client) { server.registerTool( "listBrowserTabs", { - title: "List browser tabs", - description: - "Every browser tab that currently has DevTools open, with the tabId you can pass to any other tool. " + - "Call this when a result reported otherTabs above 0, or when the user mentions a page other than the one you have been reading. " + - "The tab marked isCurrent is the one every other tool uses when you do not pass tabId. " + - "A tab on chrome://, DevTools, view-source, the Chrome Web Store, an extension page, or the PDF viewer " + - `is metadata only (access "metadata-only", "${RESTRICTED_PAGE_MESSAGE}") and cannot be scripted.`, + title: "List DevTools-connected tabs", + description: LIST_BROWSER_TABS_DESCRIPTION, outputSchema: { tabs: z.array(z.record(z.string(), z.unknown())), - currentTabId: z.union([z.number(), z.string()]).nullable(), + currentTabId: z.union([z.number(), z.string()]).nullable().describe(DEVTOOLS_TAB_ID), connectedTabs: z.number().int(), }, annotations: { - title: "List browser tabs", + title: "List DevTools-connected tabs", readOnlyHint: true, destructiveHint: false, idempotentHint: true, @@ -627,26 +628,20 @@ const TOOLS: ToolDefinition[] = [ server.registerTool( "navigateBrowser", { - title: "Navigate to a URL", - description: - "Loads a URL in the chosen browser tab without focusing it or attaching the debugger. " + - "Uses the tabId from listBrowserTabs. Requires the extension service worker, the popup " + - "switch, and --allow-input on browser-tools-mcp (browser-tools CLI: --allow-actions). " + - "chrome://, DevTools, view-source, the Chrome Web Store, and extension pages are refused. " + - "An http(s) PDF may load, then the tool fails because the viewer cannot be scripted. " + - `The error text is JSON with access "metadata-only" and message "${RESTRICTED_PAGE_MESSAGE}".`, + title: "Navigate a DevTools-connected tab", + description: NAVIGATE_BROWSER_DESCRIPTION, inputSchema: { url: z.string().describe("http(s) URL to load in the tab"), tabId: tabIdInput, }, outputSchema: { - tabId: z.union([z.number(), z.string()]), + tabId: z.union([z.number(), z.string()]).describe(DEVTOOLS_TAB_ID), requestedUrl: z.string(), finalUrl: z.string(), wasDiscarded: z.boolean(), }, annotations: { - title: "Navigate to a URL", + title: "Navigate a DevTools-connected tab", readOnlyHint: false, destructiveHint: false, idempotentHint: false, diff --git a/browser-tools-mcp/src/mcp/tool-invoke.ts b/browser-tools-mcp/src/mcp/tool-invoke.ts index 8d46ffc0..e9eb3441 100644 --- a/browser-tools-mcp/src/mcp/tool-invoke.ts +++ b/browser-tools-mcp/src/mcp/tool-invoke.ts @@ -8,6 +8,7 @@ import { } from "./resources.js"; import type { AuditCategory } from "../lighthouse/types.js"; import { RestrictedPageError, restrictedPageToolText } from "../restricted-page.js"; +import { invokeTabTool } from "../tabs/tools.js"; export type ToolContent = | { type: "text"; text: string } @@ -124,6 +125,9 @@ export async function invokeTool( client: ConnectorClient, args: Record = {} ): Promise { + const tabTool = await invokeTabTool(name, client, args); + if (tabTool) return tabTool; + switch (name) { case "listBrowserTabs": try { @@ -317,6 +321,11 @@ async function runAudit( /** Every registered MCP tool name must have an invoke implementation. */ export const INVOKABLE_TOOL_NAMES: readonly string[] = [ + "listTabs", + "readTab", + "navigateTab", + "softClick", + "softType", "listBrowserTabs", "getConsoleLogs", "getConsoleErrors", diff --git a/browser-tools-mcp/src/runtime.ts b/browser-tools-mcp/src/runtime.ts index b2d458b1..3dc5d68f 100644 --- a/browser-tools-mcp/src/runtime.ts +++ b/browser-tools-mcp/src/runtime.ts @@ -72,6 +72,21 @@ class UnavailableConnectorClient implements ConnectorClient { navigate(): Promise { return this.#fail(); } + listChromeTabs(): Promise { + return this.#fail(); + } + readChromeTab(): Promise { + return this.#fail(); + } + navigateChromeTab(): Promise { + return this.#fail(); + } + softClickChromeTab(): Promise { + return this.#fail(); + } + softTypeChromeTab(): Promise { + return this.#fail(); + } storage(): Promise { return this.#fail(); } diff --git a/browser-tools-mcp/src/tabs/contract.ts b/browser-tools-mcp/src/tabs/contract.ts new file mode 100644 index 00000000..7b1353be --- /dev/null +++ b/browser-tools-mcp/src/tabs/contract.ts @@ -0,0 +1,204 @@ +import { RESTRICTED_PAGE_MESSAGE } from "../restricted-page.js"; + +/** + * Tab-awareness contracts (AGE-584). + * + * Two id spaces, kept apart in every description: + * + * - A DevTools-connected tab id comes from listBrowserTabs. It is + * chrome.devtools.inspectedWindow.tabId for a tab whose DevTools page is + * connected to the connector. Pass it as `tabId` to the existing tools. + * - A chrome.tabs id comes from listTabs. It is chrome.tabs.Tab.id for a tab + * the browser returned. Pass it as `chromeTabId` to listTabs, readTab, + * navigateTab, softClick, and softType. + * + * Chrome often uses the same integer for both when DevTools is open on that + * tab. The tools still do not accept each other's ids: a DevTools-connected + * id only addresses a connected DevTools page, and a chrome.tabs id is only + * valid when listTabs returned it. + */ + +/** What listTabs is willing to claim. AGE-618 left Arc unmeasured. */ +export const TAB_COVERAGE = + "Tabs the browser exposes through chrome.tabs in the windows it returns. " + + "Other Arc Spaces, Little Arc, pinned favorites, split-view partners, and slept tabs may be missing. " + + "Incognito is skipped. This is not every open tab."; + +export const DEVTOOLS_TAB_ID = + "DevTools-connected tab id from listBrowserTabs (the inspected tab whose DevTools page is connected). " + + "Not a chromeTabId from listTabs. Do not pass a chrome.tabs id here."; + +export const CHROME_TAB_ID = + "chrome.tabs id from listTabs (chrome.tabs.Tab.id). Not a DevTools-connected tabId from listBrowserTabs. " + + "Pass only an id listTabs returned."; + +export const LIST_BROWSER_TABS_DESCRIPTION = + "Every browser tab that currently has DevTools open, with the DevTools-connected tabId you can pass to the telemetry tools. " + + "These ids are not chromeTabId values from listTabs. This list is only tabs with DevTools open, not every open tab. " + + "Call this when a result reported otherTabs above 0, or when the user mentions a page other than the one you have been reading. " + + "The tab marked isCurrent is the one the DevTools tools use when you do not pass tabId. " + + "A tab on chrome://, DevTools, view-source, the Chrome Web Store, an extension page, or the PDF viewer " + + `is metadata only (access "metadata-only", "${RESTRICTED_PAGE_MESSAGE}") and cannot be scripted.`; + +export const DEVTOOLS_TAB_INPUT = + "DevTools-connected tab id from listBrowserTabs. Not a chromeTabId from listTabs. " + + "Omit to use the current tab — the one DevTools was most recently opened on, which is right in almost every session. " + + "Only pass this when a result reported otherTabs above 0 and you need a specific DevTools-connected tab."; + +export const NAVIGATE_BROWSER_DESCRIPTION = + "Loads a URL in a DevTools-connected tab without focusing it or attaching the debugger. " + + "tabId is a DevTools-connected id from listBrowserTabs, not a chromeTabId from listTabs. " + + "Requires the extension service worker, the popup switch, and --allow-input on browser-tools-mcp " + + "(browser-tools CLI: --allow-actions). Does not call chrome.tabs.update({active:true}) or chrome.windows.update({focused:true}). " + + "chrome://, DevTools, view-source, the Chrome Web Store, and extension pages are refused. " + + "An http(s) PDF may load, then the tool fails because the viewer cannot be scripted. " + + `The error text is JSON with access "metadata-only" and message "${RESTRICTED_PAGE_MESSAGE}".`; + +export const LIST_TABS_DESCRIPTION = + TAB_COVERAGE + + " Each tab includes title, URL, site, window, last viewed, and whether it is asleep (discarded) or frozen. " + + "chromeTabId is a chrome.tabs id, not a DevTools-connected tabId from listBrowserTabs. " + + "Uses chrome.tabs and chrome.windows only. Does not attach the debugger and does not change focus. " + + "Needs the extension popup switch. The exclude list, empty by default, drops matching origins."; + +export const READ_TAB_DESCRIPTION = + "Reads headings, a short excerpt, and a compact snapshot of a tab from listTabs, without DevTools and without the debugger. " + + "chromeTabId is a chrome.tabs id from listTabs, not a DevTools-connected tabId from listBrowserTabs. " + + "Private details are stripped in the browser before the result leaves the page. " + + "An asleep (discarded) tab is reported as asleep and is not reloaded. A frozen tab is skipped. " + + "chrome:// pages, the Chrome Web Store, and the PDF viewer cannot be read. " + + "Needs the popup switch and host access for that site. Does not change focus."; + +export const NAVIGATE_TAB_DESCRIPTION = + "Loads a URL in the background with chrome.tabs, without DevTools and without the debugger. " + + "Pass chromeTabId from listTabs to update that tab, or omit it to open a new background tab. " + + "chromeTabId is not a DevTools-connected tabId from listBrowserTabs. " + + "Limited to the visible window until Arc Spaces are measured: a tab in another window is refused, and nothing switches window or Space. " + + "Never activates the tab or focuses the window. " + + "Gated like input: popup switch, --allow-input (browser-tools CLI: --allow-actions), and the same origin rules. " + + "Reports the final URL, whether an asleep tab was woken (wasDiscarded), and any tab or popup the page opened."; + +export const SOFT_CLICK_DESCRIPTION = + "Clicks an element in a tab from listTabs by dispatching untrusted pointer events. Does not attach the debugger and does not change focus. " + + "chromeTabId is a chrome.tabs id from listTabs, not a DevTools-connected tabId from listBrowserTabs. " + + "A submit control uses form.requestSubmit() rather than form.submit(). " + + "The result is outcome \"worked\" or \"needs a real gesture\" with a reason (file picker, clipboard, popup, fullscreen, " + + "the site checks isTrusted, anti-bot check, Google Docs or canvas app, or UI that needs the page drawn). " + + "A failed action is never reported as worked. " + + "Gated like input: popup switch, --allow-input (browser-tools CLI: --allow-actions), and the same origin rules."; + +export const SOFT_TYPE_DESCRIPTION = + "Types into an element in a tab from listTabs without the debugger and without changing focus. " + + "chromeTabId is a chrome.tabs id from listTabs, not a DevTools-connected tabId from listBrowserTabs. " + + "Ordinary inputs use the native value setter, then input and change events, so React and Vue fields update. " + + "Rich editors (contenteditable, ProseMirror, Lexical) are focused in the page and receive execCommand('insertText'). " + + "Pass submit true to submit the surrounding form with requestSubmit(). " + + "The result is outcome \"worked\" or \"needs a real gesture\" with a reason. A failed action is never reported as worked. " + + "Gated like input: popup switch, --allow-input (browser-tools CLI: --allow-actions), and the same origin rules."; + +export const SOFT_OUTCOMES = ["worked", "needs a real gesture"] as const; +export type SoftOutcome = (typeof SOFT_OUTCOMES)[number]; + +export const GESTURE_REASONS = [ + "file picker", + "clipboard", + "popup", + "fullscreen", + "the site checks isTrusted", + "anti-bot check", + "Google Docs or canvas app", + "UI that needs the page drawn", +] as const; +export type GestureReason = (typeof GESTURE_REASONS)[number]; + +export interface ChromeTabView { + chromeTabId: number; + windowId: number; + title: string; + url: string; + site: string; + active: boolean; + pinned: boolean; + /** chrome.tabs discarded. Asleep. Not reloaded by a read. */ + discarded: boolean; + frozen: boolean; + /** chrome.tabs lastAccessed, milliseconds, or null when the browser omitted it. */ + lastAccessed: number | null; + audible: boolean; + status: string; + index: number; +} + +export interface ChromeWindowView { + windowId: number; + focused: boolean; + type: string; + incognito: false; + tabs: ChromeTabView[]; +} + +export interface ChromeTabListing { + coverage: string; + visibleWindowId: number | null; + windows: ChromeWindowView[]; +} + +export interface ChromeTabHeading { + level: number; + text: string; +} + +export interface ChromeTabSnapshotNode { + depth: number; + role: string; + name: string; +} + +export interface ChromeTabRead { + chromeTabId: number; + url: string; + title: string; + site: string; + asleep: boolean; + frozen: boolean; + /** Set when the tab was not read. "frozen" or a short reason. */ + skipped: string | null; + headings: ChromeTabHeading[]; + excerpt: string; + snapshot: ChromeTabSnapshotNode[]; + hostAccess: boolean; +} + +export interface OpenedTab { + chromeTabId: number; + url: string; + windowId: number; + active: boolean; +} + +export interface SafetyCounts { + debuggerCalls: number; + focusChanges: number; +} + +export interface ChromeNavigateResult { + chromeTabId: number; + requestedUrl: string; + finalUrl: string; + wasDiscarded: boolean; + created: boolean; + visibleWindowId: number; + openedTabs: OpenedTab[]; + safety: SafetyCounts; +} + +export interface SoftInputResult { + chromeTabId: number; + outcome: SoftOutcome; + reason: GestureReason | null; + detail: string; + /** Synthetic events are never trusted. Always false. */ + trusted: false; +} + +export const TAB_TOOL_NAMES = ["listTabs", "readTab", "navigateTab", "softClick", "softType"] as const; diff --git a/browser-tools-mcp/src/tabs/listing.ts b/browser-tools-mcp/src/tabs/listing.ts new file mode 100644 index 00000000..773a9cd9 --- /dev/null +++ b/browser-tools-mcp/src/tabs/listing.ts @@ -0,0 +1,202 @@ +import { tabListed, type GatePolicy } from "../gates/capability.js"; +import { originOf } from "../lighthouse/destination.js"; +import { redactSecretsInString } from "../util/redact.js"; +import { + GESTURE_REASONS, + TAB_COVERAGE, + type ChromeNavigateResult, + type ChromeTabHeading, + type ChromeTabListing, + type ChromeTabRead, + type ChromeTabSnapshotNode, + type ChromeTabView, + type ChromeWindowView, + type GestureReason, + type OpenedTab, + type SafetyCounts, + type SoftInputResult, + type SoftOutcome, +} from "./contract.js"; + +function asRecord(value: unknown): Record | null { + return value !== null && typeof value === "object" ? (value as Record) : null; +} + +function finiteNumber(value: unknown): number | null { + return typeof value === "number" && Number.isFinite(value) ? value : null; +} + +export function siteOf(url: string): string { + return originOf(url) ?? ""; +} + +/** Drops incognito and excluded origins. Secrets in titles and URLs are redacted. */ +export function normalizeChromeTabListing(payload: unknown, policy: GatePolicy): ChromeTabListing { + const root = asRecord(payload) ?? {}; + const visibleWindowId = finiteNumber(root["visibleWindowId"]); + const rawWindows = Array.isArray(root["windows"]) ? root["windows"] : []; + const windows: ChromeWindowView[] = []; + + for (const rawWindow of rawWindows) { + const window = asRecord(rawWindow); + if (!window || window["incognito"] === true) continue; + const windowId = finiteNumber(window["windowId"]); + if (windowId === null) continue; + const rawTabs = Array.isArray(window["tabs"]) ? window["tabs"] : []; + const tabs: ChromeTabView[] = []; + for (const rawTab of rawTabs) { + const tab = asRecord(rawTab); + if (!tab || tab["incognito"] === true) continue; + const chromeTabId = finiteNumber(tab["chromeTabId"]); + if (chromeTabId === null) continue; + const url = redactSecretsInString(typeof tab["url"] === "string" ? tab["url"] : ""); + if (!tabListed(url, policy)) continue; + tabs.push({ + chromeTabId, + windowId: finiteNumber(tab["windowId"]) ?? windowId, + title: redactSecretsInString(typeof tab["title"] === "string" ? tab["title"] : "").slice(0, 300), + url, + site: siteOf(url), + active: tab["active"] === true, + pinned: tab["pinned"] === true, + discarded: tab["discarded"] === true, + frozen: tab["frozen"] === true, + lastAccessed: finiteNumber(tab["lastAccessed"]), + audible: tab["audible"] === true, + status: typeof tab["status"] === "string" ? tab["status"] : "", + index: finiteNumber(tab["index"]) ?? 0, + }); + } + windows.push({ + windowId, + focused: window["focused"] === true, + type: typeof window["type"] === "string" ? window["type"] : "normal", + incognito: false, + tabs, + }); + } + + return { coverage: TAB_COVERAGE, visibleWindowId, windows }; +} + +export function readSafety(payload: Record): SafetyCounts { + const safety = asRecord(payload["safety"]); + return { + debuggerCalls: finiteNumber(safety?.["debuggerCalls"]) ?? 0, + focusChanges: finiteNumber(safety?.["focusChanges"]) ?? 0, + }; +} + +export function assertTabActionSafe(payload: Record): SafetyCounts { + const safety = readSafety(payload); + if (safety.debuggerCalls > 0 || safety.focusChanges > 0) { + throw new Error("The tab action tried to attach the debugger or change focus, so it was refused."); + } + return safety; +} + +function text(value: unknown, max: number): string { + return redactSecretsInString(typeof value === "string" ? value : "").slice(0, max); +} + +export function parseChromeTabRead(chromeTabId: number, value: unknown): ChromeTabRead { + const read = asRecord(value) ?? {}; + const url = text(read["url"], 2000); + const headings: ChromeTabHeading[] = []; + if (Array.isArray(read["headings"])) { + for (const item of read["headings"].slice(0, 30)) { + const heading = asRecord(item); + if (!heading) continue; + const level = finiteNumber(heading["level"]); + headings.push({ + level: level !== null && level >= 1 && level <= 6 ? level : 1, + text: text(heading["text"], 200), + }); + } + } + const snapshot: ChromeTabSnapshotNode[] = []; + if (Array.isArray(read["snapshot"])) { + for (const item of read["snapshot"].slice(0, 60)) { + const node = asRecord(item); + if (!node) continue; + snapshot.push({ + depth: finiteNumber(node["depth"]) ?? 0, + role: text(node["role"], 40), + name: text(node["name"], 80), + }); + } + } + const skipped = typeof read["skipped"] === "string" && read["skipped"] ? read["skipped"].slice(0, 120) : null; + return { + chromeTabId, + url, + title: text(read["title"], 300), + site: siteOf(url), + asleep: read["asleep"] === true, + frozen: read["frozen"] === true, + skipped, + headings, + excerpt: text(read["excerpt"], 800), + snapshot, + hostAccess: read["hostAccess"] === true, + }; +} + +function parseOpenedTabs(value: unknown): OpenedTab[] { + if (!Array.isArray(value)) return []; + const opened: OpenedTab[] = []; + for (const item of value.slice(0, 20)) { + const tab = asRecord(item); + if (!tab) continue; + const chromeTabId = finiteNumber(tab["chromeTabId"]); + const windowId = finiteNumber(tab["windowId"]); + if (chromeTabId === null || windowId === null) continue; + opened.push({ + chromeTabId, + windowId, + url: text(tab["url"], 2000), + active: tab["active"] === true, + }); + } + return opened; +} + +export function parseChromeNavigate(requestedUrl: string, payload: Record): ChromeNavigateResult { + const safety = assertTabActionSafe(payload); + const chromeTabId = finiteNumber(payload["chromeTabId"]); + const visibleWindowId = finiteNumber(payload["visibleWindowId"]); + if (chromeTabId === null || visibleWindowId === null) { + throw new Error("The extension returned an incomplete navigation result."); + } + return { + chromeTabId, + requestedUrl, + finalUrl: text(payload["finalUrl"], 2000) || requestedUrl, + wasDiscarded: payload["wasDiscarded"] === true, + created: payload["created"] === true, + visibleWindowId, + openedTabs: parseOpenedTabs(payload["openedTabs"]), + safety, + }; +} + +export function parseSoftInput(chromeTabId: number, payload: Record): SoftInputResult { + assertTabActionSafe(payload); + const outcome = payload["outcome"]; + if (outcome !== "worked" && outcome !== "needs a real gesture") { + throw new Error("Soft input did not report worked or needs a real gesture."); + } + const reasonRaw = payload["reason"]; + const reason = GESTURE_REASONS.find((entry) => entry === reasonRaw) ?? null; + if (outcome === "needs a real gesture" && !reason) { + throw new Error("Soft input refused without a reason."); + } + const parsed: SoftInputResult = { + chromeTabId, + outcome: outcome as SoftOutcome, + reason: outcome === "worked" ? null : (reason as GestureReason), + detail: text(payload["detail"], 300), + trusted: false, + }; + return parsed; +} diff --git a/browser-tools-mcp/src/tabs/tools.ts b/browser-tools-mcp/src/tabs/tools.ts new file mode 100644 index 00000000..6b204f6d --- /dev/null +++ b/browser-tools-mcp/src/tabs/tools.ts @@ -0,0 +1,311 @@ +import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { z } from "zod"; + +import type { ConnectorClient } from "../mcp/client.js"; +import { + CHROME_TAB_ID, + LIST_TABS_DESCRIPTION, + NAVIGATE_TAB_DESCRIPTION, + READ_TAB_DESCRIPTION, + SOFT_CLICK_DESCRIPTION, + SOFT_TYPE_DESCRIPTION, +} from "./contract.js"; + +type TextContent = { type: "text"; text: string }; + +export type TabToolResult = { + content: TextContent[]; + structuredContent?: Record; + isError?: boolean; +}; + +function ok(structured: Record): TabToolResult { + return { + content: [{ type: "text", text: JSON.stringify(structured, null, 2) }], + structuredContent: structured, + }; +} + +function fail(error: unknown): TabToolResult { + const message = error instanceof Error ? error.message : String(error); + return { content: [{ type: "text", text: message }], isError: true }; +} + +const chromeTabIdInput = z.number().int().positive().describe(CHROME_TAB_ID); + +const selectorInput = z + .string() + .min(1) + .max(500) + .describe("CSS selector for the element in that tab. Not a DevTools-connected tab id."); + +const safetyShape = { + debuggerCalls: z.number().int(), + focusChanges: z.number().int(), +}; + +const chromeTabShape = { + chromeTabId: z.number().int().describe(CHROME_TAB_ID), + windowId: z.number().int(), + title: z.string(), + url: z.string(), + site: z.string().describe("Origin of the tab, or empty when the URL is not http(s)."), + active: z.boolean(), + pinned: z.boolean(), + discarded: z.boolean().describe("Asleep. A read reports this and does not reload the tab."), + frozen: z.boolean(), + lastAccessed: z.number().nullable().describe("When the tab was last viewed, or null if the browser omitted it."), + audible: z.boolean(), + status: z.string(), + index: z.number().int(), +}; + +const windowShape = { + windowId: z.number().int(), + focused: z.boolean(), + type: z.string(), + incognito: z.literal(false), + tabs: z.array(z.object(chromeTabShape)), +}; + +export interface TabToolDefinition { + name: string; + register(server: McpServer, client: ConnectorClient): void; +} + +function chromeTabIdFrom(args: Record): number | undefined { + const value = args["chromeTabId"]; + return typeof value === "number" ? value : undefined; +} + +/** + * Runs one chrome.tabs tool. Returns null for every other tool name so the + * MCP server and the CLI share this path. + */ +export async function invokeTabTool( + name: string, + client: ConnectorClient, + args: Record = {} +): Promise { + try { + switch (name) { + case "listTabs": + return ok((await client.listChromeTabs()) as unknown as Record); + case "readTab": { + const chromeTabId = chromeTabIdFrom(args); + if (chromeTabId === undefined) return fail(new Error("chromeTabId is required")); + return ok((await client.readChromeTab({ chromeTabId })) as unknown as Record); + } + case "navigateTab": { + const url = args["url"]; + if (typeof url !== "string" || !url.trim()) return fail(new Error("url is required")); + const chromeTabId = chromeTabIdFrom(args); + return ok( + (await client.navigateChromeTab({ + url: url.trim(), + ...(chromeTabId !== undefined ? { chromeTabId } : {}), + })) as unknown as Record + ); + } + case "softClick": { + const chromeTabId = chromeTabIdFrom(args); + const selector = args["selector"]; + if (chromeTabId === undefined || typeof selector !== "string") { + return fail(new Error("chromeTabId and selector are required")); + } + return ok( + (await client.softClickChromeTab({ chromeTabId, selector })) as unknown as Record + ); + } + case "softType": { + const chromeTabId = chromeTabIdFrom(args); + const selector = args["selector"]; + const text = args["text"]; + if (chromeTabId === undefined || typeof selector !== "string" || typeof text !== "string") { + return fail(new Error("chromeTabId, selector, and text are required")); + } + return ok( + (await client.softTypeChromeTab({ + chromeTabId, + selector, + text, + submit: args["submit"] === true, + })) as unknown as Record + ); + } + default: + return null; + } + } catch (error) { + return fail(error); + } +} + +export const TAB_TOOLS: TabToolDefinition[] = [ + { + name: "listTabs", + register(server, client) { + server.registerTool( + "listTabs", + { + title: "List tabs chrome.tabs can see", + description: LIST_TABS_DESCRIPTION, + outputSchema: { + coverage: z.string(), + visibleWindowId: z.number().int().nullable(), + windows: z.array(z.object(windowShape)), + }, + annotations: { + title: "List tabs chrome.tabs can see", + readOnlyHint: true, + destructiveHint: false, + idempotentHint: true, + openWorldHint: true, + }, + }, + async () => invokeTabTool("listTabs", client, {}) as Promise + ); + }, + }, + { + name: "readTab", + register(server, client) { + server.registerTool( + "readTab", + { + title: "Read a background tab", + description: READ_TAB_DESCRIPTION, + inputSchema: { chromeTabId: chromeTabIdInput }, + outputSchema: { + chromeTabId: z.number().int(), + url: z.string(), + title: z.string(), + site: z.string(), + asleep: z.boolean(), + frozen: z.boolean(), + skipped: z.string().nullable(), + headings: z.array(z.object({ level: z.number().int(), text: z.string() })), + excerpt: z.string(), + snapshot: z.array(z.object({ depth: z.number().int(), role: z.string(), name: z.string() })), + hostAccess: z.boolean(), + }, + annotations: { + title: "Read a background tab", + readOnlyHint: true, + destructiveHint: false, + idempotentHint: true, + openWorldHint: true, + }, + }, + async (args) => invokeTabTool("readTab", client, args) as Promise + ); + }, + }, + { + name: "navigateTab", + register(server, client) { + server.registerTool( + "navigateTab", + { + title: "Navigate in the background", + description: NAVIGATE_TAB_DESCRIPTION, + inputSchema: { + url: z.string().describe("http(s) URL to load without focusing the tab or the window."), + chromeTabId: chromeTabIdInput + .optional() + .describe(CHROME_TAB_ID + " Omit to open a new background tab in the visible window."), + }, + outputSchema: { + chromeTabId: z.number().int(), + requestedUrl: z.string(), + finalUrl: z.string(), + wasDiscarded: z.boolean(), + created: z.boolean(), + visibleWindowId: z.number().int(), + openedTabs: z.array( + z.object({ + chromeTabId: z.number().int(), + url: z.string(), + windowId: z.number().int(), + active: z.boolean(), + }) + ), + safety: z.object(safetyShape), + }, + annotations: { + title: "Navigate in the background", + readOnlyHint: false, + destructiveHint: false, + idempotentHint: false, + openWorldHint: true, + }, + }, + async (args) => invokeTabTool("navigateTab", client, args) as Promise + ); + }, + }, + { + name: "softClick", + register(server, client) { + server.registerTool( + "softClick", + { + title: "Soft click", + description: SOFT_CLICK_DESCRIPTION, + inputSchema: { chromeTabId: chromeTabIdInput, selector: selectorInput }, + outputSchema: { + chromeTabId: z.number().int(), + outcome: z.enum(["worked", "needs a real gesture"]), + reason: z.string().nullable(), + detail: z.string(), + trusted: z.literal(false), + }, + annotations: { + title: "Soft click", + readOnlyHint: false, + destructiveHint: false, + idempotentHint: false, + openWorldHint: true, + }, + }, + async (args) => invokeTabTool("softClick", client, args) as Promise + ); + }, + }, + { + name: "softType", + register(server, client) { + server.registerTool( + "softType", + { + title: "Soft type", + description: SOFT_TYPE_DESCRIPTION, + inputSchema: { + chromeTabId: chromeTabIdInput, + selector: selectorInput, + text: z.string().max(20000).describe("Text to insert. Password fields are refused."), + submit: z + .boolean() + .optional() + .describe("After a successful type, submit the surrounding form with requestSubmit()."), + }, + outputSchema: { + chromeTabId: z.number().int(), + outcome: z.enum(["worked", "needs a real gesture"]), + reason: z.string().nullable(), + detail: z.string(), + trusted: z.literal(false), + }, + annotations: { + title: "Soft type", + readOnlyHint: false, + destructiveHint: false, + idempotentHint: false, + openWorldHint: true, + }, + }, + async (args) => invokeTabTool("softType", client, args) as Promise + ); + }, + }, +]; diff --git a/browser-tools-mcp/src/tools-cli.ts b/browser-tools-mcp/src/tools-cli.ts index 193dc550..03c5d347 100644 --- a/browser-tools-mcp/src/tools-cli.ts +++ b/browser-tools-mcp/src/tools-cli.ts @@ -96,7 +96,9 @@ Resource commands: Examples: browser-tools getConnectionStatus browser-tools getConsoleLogs '{"limit":20}' + browser-tools listTabs browser-tools --allow-actions navigateBrowser '{"url":"http://localhost:3000/","tabId":1}' + browser-tools --allow-actions navigateTab '{"url":"http://127.0.0.1:3000/","chromeTabId":4}' `; } diff --git a/browser-tools-mcp/test/e2e/tab-awareness.e2e.test.ts b/browser-tools-mcp/test/e2e/tab-awareness.e2e.test.ts new file mode 100644 index 00000000..0890631b --- /dev/null +++ b/browser-tools-mcp/test/e2e/tab-awareness.e2e.test.ts @@ -0,0 +1,221 @@ +import { afterAll, beforeAll, describe, expect, it } from "vitest"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { chromium, type BrowserContext, type Page } from "playwright"; +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js"; + +import { createConnector, type Connector } from "../../src/connector/connector"; +import { InProcessConnectorClient } from "../../src/mcp/client"; +import { createMcpServer } from "../../src/mcp/server"; +import { browserAvailability } from "../helpers/browser-available"; +import { e2eChromiumOptions } from "../helpers/e2e-chromium"; +import { startFixtureServer, type FixtureServer } from "../fixtures/server"; +import { waitForPortFree } from "../helpers/port"; + +/** + * Tab awareness with DevTools closed. + * + * The other end-to-end file opens DevTools, which attaches chrome.debugger on + * purpose. This one must not: list and navigate go through chrome.tabs only, + * and the tab the user is looking at stays active. + */ +const browserSupport = await browserAvailability(); +if (!browserSupport.usable) console.warn(`\n SKIPPED: ${browserSupport.reason}\n`); + +const extensionPath = path.resolve(fileURLToPath(new URL("../../../chrome-extension", import.meta.url))); + +let connector: Connector; +let fixture: FixtureServer; +let context: BrowserContext | null = null; +let client: Client; +let closeServer: (() => Promise) | null = null; +let userDataDir: string; +let page: Page; + +beforeAll(async () => { + userDataDir = fs.mkdtempSync(path.join(os.tmpdir(), "bt-e2e-tabs-")); + fixture = await startFixtureServer(); + await waitForPortFree(3026); + connector = await createConnector({ + port: 3026, + screenshotDir: fs.mkdtempSync(path.join(os.tmpdir(), "bt-e2e-tabs-shots-")), + allowInput: true, + heartbeatIntervalMs: 30_000, + }); + + const { server } = createMcpServer({ client: new InProcessConnectorClient(connector) }); + const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); + client = new Client({ name: "e2e-tabs", version: "1.0.0" }); + await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]); + closeServer = async () => { + await client.close(); + await server.close(); + }; + + if (!browserSupport.usable) return; + + context = await chromium.launchPersistentContext(userDataDir, { + ...browserSupport.launchOptions, + viewport: { width: 1100, height: 800 }, + ...e2eChromiumOptions([ + `--disable-extensions-except=${extensionPath}`, + `--load-extension=${extensionPath}`, + "--no-first-run", + "--no-default-browser-check", + ]), + }); + page = context.pages()[0] ?? (await context.newPage()); + await page.goto(fixture.url, { waitUntil: "domcontentloaded" }); +}, 240_000); + +afterAll(async () => { + await closeServer?.(); + await context?.close().catch(() => {}); + await connector?.close(); + await fixture?.close(); + fs.rmSync(userDataDir, { recursive: true, force: true }); +}); + +async function extensionWorker() { + const existing = context!.serviceWorkers().find((worker) => worker.url().includes("chrome-extension://")); + if (existing) return existing; + return context!.waitForEvent("serviceworker", { timeout: 30_000 }); +} + +async function callTool(name: string, args: Record = {}) { + const result = await client.callTool({ name, arguments: args }); + const text = result.content.find((block) => block.type === "text"); + const body = text && "text" in text ? text.text : ""; + if (result.isError) throw new Error(body); + return JSON.parse(body) as Record; +} + +async function browserState() { + const sw = await extensionWorker(); + return sw.evaluate(async () => { + const chromeApi = (globalThis as unknown as { chrome: any }).chrome; + const [active] = await chromeApi.tabs.query({ active: true, lastFocusedWindow: true }); + const safety = (globalThis as unknown as { __btmcpSafety?: { snapshot: () => { debuggerCalls: number; focusChanges: number } } }).__btmcpSafety?.snapshot() ?? { + debuggerCalls: -1, + focusChanges: -1, + }; + return { + activeId: active && active.id, + activeUrl: active && active.url, + windowId: active && active.windowId, + safety, + }; + }); +} + +/** True only if this extension has called chrome.debugger.attach on the tab. */ +async function extensionDebuggerAttached(tabId: number): Promise { + const sw = await extensionWorker(); + return sw.evaluate(async (id: number) => { + const chromeApi = (globalThis as unknown as { chrome: any }).chrome; + try { + await new Promise((resolve, reject) => { + chromeApi.debugger.sendCommand({ tabId: id }, "Runtime.evaluate", { expression: "1" }, () => { + const message = chromeApi.runtime.lastError?.message; + if (message) reject(new Error(message)); + else resolve(true); + }); + }); + return true; + } catch { + return false; + } + }, tabId); +} + +describe("tab awareness without DevTools", () => { + it.skipIf(!browserSupport.usable)( + "lists, navigates, reads, and soft-inputs without attaching the debugger or stealing focus", + async () => { + const sw = await extensionWorker(); + await sw.evaluate(async () => { + const chromeApi = (globalThis as unknown as { chrome: any }).chrome; + await chromeApi.storage.session.set({ btmcpPopupSwitch: true }); + }); + + let listing: Record | undefined; + const deadline = Date.now() + 45_000; + let lastError = ""; + while (Date.now() < deadline) { + try { + listing = await callTool("listTabs"); + const blob = JSON.stringify(listing); + if (blob.includes(String(fixture.port))) break; + } catch (error) { + lastError = error instanceof Error ? error.message : String(error); + } + await new Promise((resolve) => setTimeout(resolve, 300)); + } + if (!listing || !JSON.stringify(listing).includes(String(fixture.port))) { + throw new Error(`listTabs did not see the fixture. Last error: ${lastError}`); + } + + expect(listing["coverage"]).toMatch(/This is not every open tab/); + expect(String(listing["coverage"])).not.toMatch(/every tab you have|all open tabs/); + + const before = await browserState(); + expect(before.safety.debuggerCalls).toBe(0); + expect(before.safety.focusChanges).toBe(0); + + const opened = await callTool("navigateTab", { url: `${fixture.url}form` }); + expect(opened["created"]).toBe(true); + expect(opened["safety"]).toEqual({ debuggerCalls: 0, focusChanges: 0 }); + const chromeTabId = opened["chromeTabId"] as number; + + const afterNavigate = await browserState(); + expect(afterNavigate.activeId).toBe(before.activeId); + expect(afterNavigate.activeUrl).toBe(before.activeUrl); + expect(afterNavigate.windowId).toBe(before.windowId); + expect(afterNavigate.safety).toEqual({ debuggerCalls: 0, focusChanges: 0 }); + expect(page.url()).toBe(fixture.url); + + const read = await callTool("readTab", { chromeTabId }); + expect(read["asleep"]).toBe(false); + expect(JSON.stringify(read["headings"])).toContain("Soft form"); + expect(JSON.stringify(read)).not.toContain("user@example.com"); + + const file = await callTool("softClick", { chromeTabId, selector: "#file" }); + expect(file).toMatchObject({ outcome: "needs a real gesture", reason: "file picker", trusted: false }); + + const typed = await callTool("softType", { + chromeTabId, + selector: "#name", + text: "Ada", + submit: true, + }); + expect(typed).toMatchObject({ outcome: "worked", trusted: false }); + + const settled = await browserState(); + expect(settled.activeId).toBe(before.activeId); + expect(settled.activeUrl).toBe(before.activeUrl); + expect(settled.safety).toEqual({ debuggerCalls: 0, focusChanges: 0 }); + + // The result page's title replaces the URL only after load. listTabs can + // observe the tab while it is still loading. + let again: Record | undefined; + const titleDeadline = Date.now() + 5_000; + while (Date.now() < titleDeadline) { + again = await callTool("listTabs"); + if (JSON.stringify(again).includes("Form result")) break; + await new Promise((resolve) => setTimeout(resolve, 100)); + } + const tabs = JSON.stringify(again); + expect(tabs).toContain("Form result"); + expect(tabs).toContain(String(before.activeId)); + + // After the product path. sendCommand counts as a debugger call, so this + // stays last. A miss means the extension never attached. + expect(await extensionDebuggerAttached(chromeTabId)).toBe(false); + expect(await extensionDebuggerAttached(before.activeId as number)).toBe(false); + }, + 180_000 + ); +}); diff --git a/browser-tools-mcp/test/fixtures/server.ts b/browser-tools-mcp/test/fixtures/server.ts index f6bc406e..b7fa75d7 100644 --- a/browser-tools-mcp/test/fixtures/server.ts +++ b/browser-tools-mcp/test/fixtures/server.ts @@ -118,6 +118,29 @@ export async function startFixtureServer(): Promise { return; } + if (url === "/form" || url.startsWith("/form?")) { + res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }); + res.end(` + Soft form + +

Soft form

+
+ + +
+ +
+

user@example.com

+ `); + return; + } + + if (url.startsWith("/form-result")) { + res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }); + res.end("Form result

Form result

"); + return; + } + if (url === "/image.png") { res.writeHead(200, { "Content-Type": "image/png" }); res.end( diff --git a/browser-tools-mcp/test/helpers/fake-extension.ts b/browser-tools-mcp/test/helpers/fake-extension.ts index d2931ad2..372b0ff7 100644 --- a/browser-tools-mcp/test/helpers/fake-extension.ts +++ b/browser-tools-mcp/test/helpers/fake-extension.ts @@ -15,6 +15,10 @@ export interface FakeExtensionOptions { onScreenshot?: (msg: any) => Promise | unknown; onRefresh?: (msg: any) => Promise | unknown; onNavigate?: (msg: any) => Promise | unknown; + onListChromeTabs?: (msg: any) => Promise | unknown; + onReadChromeTab?: (msg: any) => Promise | unknown; + onNavigateChromeTab?: (msg: any) => Promise | unknown; + onSoftInput?: (msg: any) => Promise | unknown; onStorage?: (msg: any) => Promise | unknown; /** `worker` answers capability probes and is not a DevTools tab. */ role?: "devtools" | "worker"; @@ -110,10 +114,73 @@ export class FakeExtension { const custom = this.#options.onNavigate; const payload = custom ? await custom(msg) - : { ok: true, finalUrl: msg.url, wasDiscarded: false }; + : { ok: true, finalUrl: msg.url, wasDiscarded: false, safety: { debuggerCalls: 0, focusChanges: 0 } }; this.send({ type: "navigate-result", requestId: msg.requestId, ...(payload as object) }); break; } + case "list-chrome-tabs": { + const custom = this.#options.onListChromeTabs; + const payload = custom + ? await custom(msg) + : { ok: true, visibleWindowId: 1, windows: [], safety: { debuggerCalls: 0, focusChanges: 0 } }; + this.send({ type: "chrome-tabs-result", requestId: msg.requestId, ...(payload as object) }); + break; + } + case "read-chrome-tab": { + const custom = this.#options.onReadChromeTab; + const payload = custom + ? await custom(msg) + : { + ok: true, + safety: { debuggerCalls: 0, focusChanges: 0 }, + read: { + url: "http://127.0.0.1/", + title: "", + asleep: false, + frozen: false, + skipped: null, + headings: [], + excerpt: "", + snapshot: [], + hostAccess: true, + }, + }; + this.send({ type: "chrome-tab-read-result", requestId: msg.requestId, ...(payload as object) }); + break; + } + case "navigate-chrome-tab": { + const custom = this.#options.onNavigateChromeTab; + const payload = custom + ? await custom(msg) + : { + ok: true, + chromeTabId: msg.chromeTabId ?? 1, + finalUrl: msg.url, + wasDiscarded: false, + created: msg.create === true, + visibleWindowId: 1, + openedTabs: [], + safety: { debuggerCalls: 0, focusChanges: 0 }, + }; + this.send({ type: "navigate-chrome-result", requestId: msg.requestId, ...(payload as object) }); + break; + } + case "soft-input": { + const custom = this.#options.onSoftInput; + const payload = custom + ? await custom(msg) + : { + ok: true, + chromeTabId: msg.chromeTabId, + outcome: "worked", + reason: null, + detail: "ok", + trusted: false, + safety: { debuggerCalls: 0, focusChanges: 0 }, + }; + this.send({ type: "soft-input-result", requestId: msg.requestId, ...(payload as object) }); + break; + } case "get-storage": { const custom = this.#options.onStorage; const payload = custom diff --git a/browser-tools-mcp/test/integration/mcp-server.test.ts b/browser-tools-mcp/test/integration/mcp-server.test.ts index 2efdc3c3..de18dc93 100644 --- a/browser-tools-mcp/test/integration/mcp-server.test.ts +++ b/browser-tools-mcp/test/integration/mcp-server.test.ts @@ -71,7 +71,12 @@ describe("tool registration", () => { "getPageInfo", "getSelectedElement", "listBrowserTabs", + "listTabs", "navigateBrowser", + "navigateTab", + "readTab", + "softClick", + "softType", "refreshBrowser", "runAccessibilityAudit", "runBestPracticesAudit", @@ -103,6 +108,8 @@ describe("tool registration", () => { "getSelectedElement", "getPageInfo", "getConnectionStatus", + "listTabs", + "readTab", ]) { expect(byName.get(name)?.annotations?.readOnlyHint, name).toBe(true); } @@ -112,6 +119,9 @@ describe("tool registration", () => { const { tools } = await client.listTools(); const byName = new Map(tools.map((t) => [t.name, t])); + expect(byName.get("navigateTab")?.annotations?.readOnlyHint).toBe(false); + expect(byName.get("softClick")?.annotations?.readOnlyHint).toBe(false); + expect(byName.get("softType")?.annotations?.readOnlyHint).toBe(false); expect(byName.get("wipeLogs")?.annotations?.readOnlyHint).toBe(false); expect(byName.get("wipeLogs")?.annotations?.destructiveHint).toBe(true); expect(byName.get("refreshBrowser")?.annotations?.readOnlyHint).toBe(false); diff --git a/browser-tools-mcp/test/integration/tab-awareness.test.ts b/browser-tools-mcp/test/integration/tab-awareness.test.ts new file mode 100644 index 00000000..747e3cf4 --- /dev/null +++ b/browser-tools-mcp/test/integration/tab-awareness.test.ts @@ -0,0 +1,231 @@ +import { afterEach, describe, expect, it } from "vitest"; +import os from "node:os"; +import path from "node:path"; +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js"; + +import { createConnector } from "../../src/connector/connector"; +import { InProcessConnectorClient } from "../../src/mcp/client"; +import { createMcpServer } from "../../src/mcp/server"; +import { invokeTool } from "../../src/mcp/tool-invoke"; +import { TAB_COVERAGE } from "../../src/tabs/contract"; +import { GateReason } from "../../src/gates/capability"; +import { FakeExtension } from "../helpers/fake-extension"; + +describe("chrome.tabs tools", () => { + let connector: Awaited> | undefined; + let worker: FakeExtension | undefined; + let devtools: FakeExtension | undefined; + let probePopup = false; + + afterEach(async () => { + await devtools?.close(); + await worker?.close(); + await connector?.close(); + probePopup = false; + }); + + async function start(allowInput: boolean) { + const screenshotDir = path.join(os.tmpdir(), `bt-tabs-${Date.now()}-${Math.random()}`); + connector = await createConnector({ port: 0, screenshotDir, allowInput }); + worker = new FakeExtension({ + port: connector.port, + role: "worker", + onCapabilityProbe: () => ({ + popupEnabled: probePopup, + panelEnabled: false, + liveUrl: "http://127.0.0.1:3000/app", + excludeOrigins: [], + }), + onListChromeTabs: () => ({ + ok: true, + visibleWindowId: 1, + windows: [ + { + windowId: 1, + focused: true, + type: "normal", + incognito: false, + tabs: [ + { + chromeTabId: 4, + windowId: 1, + title: "Fixture", + url: "http://127.0.0.1:3000/app", + active: true, + discarded: false, + frozen: false, + lastAccessed: 10, + index: 0, + }, + ], + }, + { + windowId: 9, + focused: false, + type: "normal", + incognito: true, + tabs: [{ chromeTabId: 99, windowId: 9, title: "Hidden", url: "https://secret.example/", active: true }], + }, + ], + safety: { debuggerCalls: 0, focusChanges: 0 }, + }), + onNavigateChromeTab: (msg) => ({ + ok: true, + chromeTabId: msg.chromeTabId ?? 15, + finalUrl: msg.url, + wasDiscarded: msg.chromeTabId === 4, + created: msg.create === true, + visibleWindowId: 1, + openedTabs: [{ chromeTabId: 16, url: "http://127.0.0.1:3000/popup", windowId: 1, active: false }], + safety: { debuggerCalls: 0, focusChanges: 0 }, + }), + onReadChromeTab: () => ({ + ok: true, + safety: { debuggerCalls: 0, focusChanges: 0 }, + read: { + url: "http://127.0.0.1:3000/app", + title: "Fixture", + asleep: true, + frozen: false, + skipped: "asleep", + headings: [], + excerpt: "", + snapshot: [], + hostAccess: true, + }, + }), + onSoftInput: (msg) => ({ + ok: true, + outcome: msg.selector === "#file" ? "needs a real gesture" : "worked", + reason: msg.selector === "#file" ? "file picker" : null, + detail: msg.selector === "#file" ? "A file picker needs a real gesture." : "Value set", + trusted: false, + safety: { debuggerCalls: 0, focusChanges: 0 }, + }), + }); + await worker.connect(); + worker.send({ type: "capability-state", popupEnabled: true }); + probePopup = true; + await expect.poll(async () => (await connector!.checkCapability("listTabs")).allowed).toBe(true); + } + + it("lists chrome.tabs metadata and drops incognito", async () => { + await start(false); + const listing = await connector!.listChromeTabs(); + expect(listing.coverage).toBe(TAB_COVERAGE); + expect(listing.windows).toHaveLength(1); + expect(listing.windows[0]?.tabs[0]).toMatchObject({ chromeTabId: 4, site: "http://127.0.0.1:3000", lastAccessed: 10 }); + expect(JSON.stringify(listing)).not.toContain("secret.example"); + const sent = worker!.received.filter((message) => message.type === "list-chrome-tabs"); + expect(sent).toHaveLength(1); + expect(JSON.stringify(sent)).not.toMatch(/active"\s*:\s*true|focused"\s*:\s*true|debugger/); + }); + + it("navigates in the background only when input is allowed, and reports popups", async () => { + await start(true); + const created = await connector!.navigateChromeTab({ url: "http://127.0.0.1:3000/next" }); + expect(created.created).toBe(true); + expect(created.chromeTabId).toBe(15); + expect(created.openedTabs[0]?.url).toContain("/popup"); + expect(created.safety).toEqual({ debuggerCalls: 0, focusChanges: 0 }); + const message = worker!.received.find((entry) => entry.type === "navigate-chrome-tab"); + expect(message.create).toBe(true); + expect(message.active).toBeUndefined(); + expect(message.focused).toBeUndefined(); + + const updated = await connector!.navigateChromeTab({ + url: "http://127.0.0.1:3000/woken", + chromeTabId: 4, + }); + expect(updated.wasDiscarded).toBe(true); + expect(updated.created).toBe(false); + }); + + it("refuses navigation when input is off and when the action would change focus", async () => { + await start(false); + await expect + .poll(async () => + (await connector!.checkCapability("navigate", { + creatingTab: true, + destinationUrl: "http://127.0.0.1:3000/next", + })).reason + ) + .toBe(GateReason.inputOff); + await expect(connector!.navigateChromeTab({ url: "http://127.0.0.1:3000/next" })).rejects.toThrow(GateReason.inputOff); + + await connector!.close(); + await worker!.close(); + await start(true); + worker!.received.length = 0; + const previous = worker!; + // Replace the navigate handler by closing and using a worker that reports a focus change. + await previous.close(); + worker = new FakeExtension({ + port: connector!.port, + role: "worker", + onCapabilityProbe: () => ({ + popupEnabled: true, + panelEnabled: false, + liveUrl: "http://127.0.0.1:3000/app", + excludeOrigins: [], + }), + onNavigateChromeTab: () => ({ + ok: true, + chromeTabId: 4, + finalUrl: "http://127.0.0.1:3000/next", + wasDiscarded: false, + created: false, + visibleWindowId: 1, + openedTabs: [], + safety: { debuggerCalls: 0, focusChanges: 1 }, + }), + }); + await worker.connect(); + worker.send({ type: "capability-state", popupEnabled: true }); + await expect + .poll(async () => + (await connector!.checkCapability("navigate", { + tabId: 4, + destinationUrl: "http://127.0.0.1:3000/next", + })).allowed + ) + .toBe(true); + await expect( + connector!.navigateChromeTab({ url: "http://127.0.0.1:3000/next", chromeTabId: 4 }) + ).rejects.toThrow(/change focus/); + }); + + it("reads an asleep tab and reports soft click outcomes through MCP and the CLI path", async () => { + await start(true); + const read = await connector!.readChromeTab({ chromeTabId: 4 }); + expect(read).toMatchObject({ asleep: true, skipped: "asleep", chromeTabId: 4 }); + + const click = await connector!.softClickChromeTab({ chromeTabId: 4, selector: "#file" }); + expect(click).toMatchObject({ outcome: "needs a real gesture", reason: "file picker", trusted: false }); + const typed = await connector!.softTypeChromeTab({ chromeTabId: 4, selector: "#name", text: "Ada" }); + expect(typed).toMatchObject({ outcome: "worked", trusted: false }); + + const client = new InProcessConnectorClient(connector!); + const invoked = await invokeTool("listTabs", client, {}); + expect(invoked.isError).toBeUndefined(); + expect(invoked.structuredContent?.["coverage"]).toBe(TAB_COVERAGE); + + const { server } = createMcpServer({ client }); + const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); + const mcp = new Client({ name: "tab-test", version: "1.0.0" }); + await Promise.all([server.connect(serverTransport), mcp.connect(clientTransport)]); + const listed = await mcp.listTools(); + const listTabs = listed.tools.find((tool) => tool.name === "listTabs"); + const navigate = listed.tools.find((tool) => tool.name === "navigateTab"); + expect(listTabs?.description).toContain("This is not every open tab"); + expect(listTabs?.description).not.toMatch(/every tab you have|all open tabs/); + expect(navigate?.description).toContain("chromeTabId"); + expect(navigate?.description).toContain("not a DevTools-connected tabId"); + expect(navigate?.description).toContain("visible window"); + const called = await mcp.callTool({ name: "softType", arguments: { chromeTabId: 4, selector: "#name", text: "Ada" } }); + expect(called.isError).toBeUndefined(); + await mcp.close(); + await server.close(); + }); +}); diff --git a/browser-tools-mcp/test/unit/capability-gates.test.ts b/browser-tools-mcp/test/unit/capability-gates.test.ts index 1a501b33..4e6b1616 100644 --- a/browser-tools-mcp/test/unit/capability-gates.test.ts +++ b/browser-tools-mcp/test/unit/capability-gates.test.ts @@ -180,6 +180,57 @@ describe("origin allowlist", () => { policy: policy({ allowInput: true, allowEval: true }), }); + it("checks only the destination when opening a new background tab", () => { + expect( + decideCapability("navigate", { + ...open, + creatingTab: true, + liveUrl: null, + destinationUrl: "http://127.0.0.1:3000/next", + }) + ).toEqual({ allowed: true, reason: GateReason.allowed }); + expect( + decideCapability("navigate", { + ...open, + creatingTab: true, + destinationUrl: "https://example.com/", + }) + ).toEqual({ allowed: false, reason: GateReason.destinationNotAllowed }); + expect( + decideCapability("navigate", { + ...open, + creatingTab: true, + liveUrl: null, + destinationUrl: null, + }) + ).toEqual({ allowed: false, reason: GateReason.destinationMissing }); + }); + + it("refuses a restricted destination when opening a new background tab", () => { + expect( + decideCapability("navigate", { + ...open, + creatingTab: true, + liveUrl: null, + destinationUrl: "chrome://settings", + }) + ).toEqual({ allowed: false, reason: GateReason.restricted }); + expect( + decideCapability("navigate", { + ...open, + creatingTab: true, + destinationUrl: "https://chromewebstore.google.com/detail/ext", + }) + ).toEqual({ allowed: false, reason: GateReason.restricted }); + expect( + decideCapability("navigate", { + ...open, + creatingTab: true, + destinationUrl: "http://localhost:3000/manual.pdf", + }).allowed + ).toBe(true); + }); + it("allows local addresses by default and refuses a public origin until it is listed", () => { expect( decideCapability("softClick", { ...open, liveUrl: "http://localhost:3000/app" }).allowed diff --git a/browser-tools-mcp/test/unit/extension-gates.test.ts b/browser-tools-mcp/test/unit/extension-gates.test.ts index a518bbd3..5df781c4 100644 --- a/browser-tools-mcp/test/unit/extension-gates.test.ts +++ b/browser-tools-mcp/test/unit/extension-gates.test.ts @@ -85,6 +85,25 @@ describe("extension confirmBeforeAct", () => { ).toEqual({ allowed: false, reason: "tab URL is missing" }); }); + it("allows a new background tab without a live URL while the popup switch is on", () => { + expect( + gates.confirmBeforeAct({ + action: "navigate", + popupEnabled: true, + panelEnabled: false, + creatingTab: true, + }) + ).toEqual({ allowed: true, reason: "allowed" }); + expect( + gates.confirmBeforeAct({ + action: "navigate", + popupEnabled: false, + panelEnabled: false, + creatingTab: true, + }) + ).toEqual({ allowed: false, reason: "popup switch is off" }); + }); + it("allows a list and a matching live origin only while the switch is on", () => { expect( gates.confirmBeforeAct({ @@ -108,14 +127,35 @@ describe("extension confirmBeforeAct", () => { describe("worker probe", () => { const worker = fs.readFileSync(path.join(extensionDir, "worker.js"), "utf8"); + const actions = fs.readFileSync(path.join(extensionDir, "tab-actions.js"), "utf8"); + const page = fs.readFileSync(path.join(extensionDir, "tab-page.js"), "utf8"); + const safety = fs.readFileSync(path.join(extensionDir, "tab-safety.js"), "utf8"); it("reads tabs for probes and navigate without the debugger or focus changes", () => { expect(worker).toContain("tabs.get"); expect(worker).toContain("navigate-tab"); - expect(worker).toMatch(/tabs\.update\([^)]*active:\s*false/); + expect(worker).toContain("list-chrome-tabs"); expect(worker).not.toMatch(/chrome\.debugger|api\.debugger|\.attach\(/); expect(worker).not.toContain("windows.update"); expect(worker).not.toContain("executeScript"); expect(worker).not.toContain("silent-debugger"); + expect(worker).not.toMatch(/active\s*:\s*true/); + expect(worker).not.toMatch(/focused\s*:\s*true/); + }); + + it("keeps chrome.tabs actions off the debugger and off focus changes", () => { + const behavior = actions + page; + expect(behavior).not.toMatch(/chrome\.debugger|api\.debugger/); + expect(behavior).not.toMatch(/active\s*:\s*true/); + expect(behavior).not.toMatch(/focused\s*:\s*true/); + expect(behavior).not.toContain("silent-debugger"); + expect(behavior).not.toContain("--disable-features"); + expect(actions).toContain("active: false"); + expect(actions).toContain("visible window"); + expect(page).toContain("requestSubmit"); + expect(page).toContain("insertText"); + expect(page).toContain("needs a real gesture"); + expect(safety).toContain("Refusing to change focus."); + expect(safety).not.toContain("silent-debugger"); }); }); diff --git a/browser-tools-mcp/test/unit/tab-contract.test.ts b/browser-tools-mcp/test/unit/tab-contract.test.ts new file mode 100644 index 00000000..8021a740 --- /dev/null +++ b/browser-tools-mcp/test/unit/tab-contract.test.ts @@ -0,0 +1,85 @@ +import { describe, expect, it } from "vitest"; + +import { + CHROME_TAB_ID, + DEVTOOLS_TAB_ID, + GESTURE_REASONS, + LIST_TABS_DESCRIPTION, + NAVIGATE_TAB_DESCRIPTION, + READ_TAB_DESCRIPTION, + SOFT_CLICK_DESCRIPTION, + SOFT_TYPE_DESCRIPTION, + TAB_COVERAGE, + TAB_TOOL_NAMES, +} from "../../src/tabs/contract"; +import { + DEVTOOLS_TAB_INPUT, + LIST_BROWSER_TABS_DESCRIPTION, + NAVIGATE_BROWSER_DESCRIPTION, +} from "../../src/tabs/contract"; + +describe("tab id contract", () => { + it("keeps DevTools-connected ids and chrome.tabs ids in separate sentences", () => { + expect(DEVTOOLS_TAB_ID).toMatch(/listBrowserTabs/); + expect(DEVTOOLS_TAB_ID).toMatch(/Not a chromeTabId/); + expect(CHROME_TAB_ID).toMatch(/listTabs/); + expect(CHROME_TAB_ID).toMatch(/Not a DevTools-connected tabId/); + expect(DEVTOOLS_TAB_INPUT).toMatch(/Not a chromeTabId/); + }); + + it("does not claim listBrowserTabs is every open tab", () => { + expect(LIST_BROWSER_TABS_DESCRIPTION).toMatch(/not every open tab/); + expect(LIST_BROWSER_TABS_DESCRIPTION).toMatch(/not chromeTabId/); + }); + + it("describes navigateBrowser as the DevTools-connected path", () => { + expect(NAVIGATE_BROWSER_DESCRIPTION).toMatch(/listBrowserTabs/); + expect(NAVIGATE_BROWSER_DESCRIPTION).toMatch(/not a chromeTabId/); + expect(NAVIGATE_BROWSER_DESCRIPTION).not.toMatch(/silent-debugger/); + expect(NAVIGATE_BROWSER_DESCRIPTION).toMatch(/active:true/); + expect(NAVIGATE_BROWSER_DESCRIPTION).toMatch(/focused:true/); + }); +}); + +describe("chrome.tabs tool descriptions", () => { + it("uses the measured coverage sentence and does not say every open tab", () => { + expect(TAB_COVERAGE).toBe( + "Tabs the browser exposes through chrome.tabs in the windows it returns. " + + "Other Arc Spaces, Little Arc, pinned favorites, split-view partners, and slept tabs may be missing. " + + "Incognito is skipped. This is not every open tab." + ); + expect(LIST_TABS_DESCRIPTION.startsWith(TAB_COVERAGE)).toBe(true); + expect(LIST_TABS_DESCRIPTION).toMatch(/This is not every open tab/); + expect(LIST_TABS_DESCRIPTION).not.toMatch(/every tab you have|all open tabs|see every/i); + for (const text of [READ_TAB_DESCRIPTION, NAVIGATE_TAB_DESCRIPTION, SOFT_CLICK_DESCRIPTION, SOFT_TYPE_DESCRIPTION]) { + expect(text).toMatch(/chromeTabId/); + expect(text).toMatch(/not a DevTools-connected tabId/); + expect(text).not.toMatch(/every open tab/i); + expect(text).not.toMatch(/silent-debugger/); + } + }); + + it("keeps background navigate inside the visible window and gated like input", () => { + expect(NAVIGATE_TAB_DESCRIPTION).toMatch(/visible window/); + expect(NAVIGATE_TAB_DESCRIPTION).toMatch(/--allow-input/); + expect(NAVIGATE_TAB_DESCRIPTION).toMatch(/wasDiscarded/); + expect(NAVIGATE_TAB_DESCRIPTION).not.toMatch(/active:\s*true/); + }); + + it("names both soft-input outcomes and the gesture reasons", () => { + expect(SOFT_CLICK_DESCRIPTION).toMatch(/"worked"/); + expect(SOFT_TYPE_DESCRIPTION).toMatch(/"needs a real gesture"/); + expect(SOFT_TYPE_DESCRIPTION).toMatch(/native value setter/); + expect(SOFT_TYPE_DESCRIPTION).toMatch(/insertText/); + expect(SOFT_CLICK_DESCRIPTION).toMatch(/requestSubmit/); + for (const reason of GESTURE_REASONS) { + expect(SOFT_CLICK_DESCRIPTION).toContain(reason); + } + }); + + it("lists the chrome.tabs tools separately from listBrowserTabs", () => { + expect([...TAB_TOOL_NAMES]).toEqual(["listTabs", "readTab", "navigateTab", "softClick", "softType"]); + expect(TAB_TOOL_NAMES).not.toContain("listBrowserTabs"); + expect(TAB_TOOL_NAMES).not.toContain("navigateBrowser"); + }); +}); diff --git a/browser-tools-mcp/test/unit/tab-extension.test.ts b/browser-tools-mcp/test/unit/tab-extension.test.ts new file mode 100644 index 00000000..0d5b47c1 --- /dev/null +++ b/browser-tools-mcp/test/unit/tab-extension.test.ts @@ -0,0 +1,342 @@ +import { describe, expect, it } from "vitest"; +import fs from "node:fs"; +import path from "node:path"; +import vm from "node:vm"; +import { fileURLToPath } from "node:url"; + +const extensionDir = path.resolve(fileURLToPath(new URL("../../../chrome-extension", import.meta.url))); + +function loadExtension(chromeApi: Record, documentMock?: Record) { + const context: Record = { + URL, + Promise, + setTimeout, + clearTimeout, + globalThis: {}, + api: chromeApi, + document: documentMock, + location: { hostname: "127.0.0.1" }, + HTMLInputElement: class HTMLInputElement {}, + HTMLTextAreaElement: class HTMLTextAreaElement {}, + Event: class Event { + type: string; + bubbles: boolean; + constructor(type: string, init: { bubbles?: boolean } = {}) { + this.type = type; + this.bubbles = init.bubbles === true; + } + }, + MouseEvent: class MouseEvent { + type: string; + constructor(type: string) { + this.type = type; + } + }, + PointerEvent: class PointerEvent { + type: string; + constructor(type: string) { + this.type = type; + } + }, + NodeFilter: { SHOW_TEXT: 4, FILTER_REJECT: 2, FILTER_ACCEPT: 1 }, + }; + context["globalThis"] = context; + vm.createContext(context); + for (const file of ["gates.js", "tab-safety.js", "tab-page.js", "tab-actions.js"]) { + vm.runInContext(fs.readFileSync(path.join(extensionDir, file), "utf8"), context); + } + return context as { + BTMCP_SAFETY: { + install: (api: unknown) => void; + snapshot: () => { debuggerCalls: number; focusChanges: number }; + tabsUpdate: (api: unknown, tabId: number, props: { url: string; active: boolean }) => Promise; + }; + BTMCP_TABS: { + list: (api: unknown, message: unknown, respond: (id: string, payload: Record) => void) => Promise; + navigateChrome: (api: unknown, message: unknown, respond: (id: string, payload: Record) => void) => Promise; + read: (api: unknown, message: unknown, respond: (id: string, payload: Record) => void) => Promise; + soft: (api: unknown, message: unknown, respond: (id: string, payload: Record) => void) => Promise; + }; + btmcpScrubText: (value: string) => string; + btmcpSoftAct: (command: Record) => { outcome: string; reason: string | null; trusted: boolean }; + btmcpReadPage: () => { headings: unknown[]; excerpt: string }; + }; +} + +function storageArea(initial: Record = {}) { + const data = { ...initial }; + return { + get(key: string | string[], callback: (stored: Record) => void) { + const keys = Array.isArray(key) ? key : [key]; + const stored: Record = {}; + for (const name of keys) stored[name] = data[name]; + callback(stored); + }, + set(value: Record, callback?: () => void) { + Object.assign(data, value); + callback?.(); + }, + }; +} + +describe("tab safety wrapper", () => { + it("counts debugger calls and refuses to activate a tab or focus a window", async () => { + const calls: string[] = []; + const api = { + debugger: { + attach: () => { + calls.push("attach"); + }, + }, + tabs: { + update: (id: number, props: unknown) => { + calls.push(`update:${id}:${JSON.stringify(props)}`); + return Promise.resolve(props); + }, + create: () => Promise.resolve({ id: 1 }), + }, + windows: { + update: () => { + calls.push("windows.update"); + return Promise.resolve(); + }, + }, + }; + const loaded = loadExtension(api); + loaded.BTMCP_SAFETY.install(api); + api.debugger.attach(); + expect(loaded.BTMCP_SAFETY.snapshot().debuggerCalls).toBe(1); + expect(calls).toContain("attach"); + expect(() => api.tabs.update(3, { url: "http://127.0.0.1/", active: true })).toThrow(/focus/); + expect(() => api.windows.update(1, { focused: true })).toThrow(/focus/); + expect(calls.some((call) => call.startsWith("update:"))).toBe(false); + expect(calls).not.toContain("windows.update"); + await loaded.BTMCP_SAFETY.tabsUpdate(api, 3, { url: "http://127.0.0.1/next", active: false }); + expect(calls).toContain('update:3:{"url":"http://127.0.0.1/next","active":false}'); + expect(loaded.BTMCP_SAFETY.snapshot().focusChanges).toBe(2); + }); +}); + +describe("chrome.tabs actions", () => { + function apiFor(tabs: Record>, windows: Record[]) { + const calls: { method: string; props?: unknown }[] = []; + const api = { + storage: { + session: storageArea({ btmcpPopupSwitch: true }), + local: storageArea({ btmcpExcludeOrigins: [] }), + }, + tabs: { + get: async (id: number) => tabs[id], + update: async (id: number, props: Record) => { + calls.push({ method: "tabs.update", props }); + return { ...tabs[id], ...props }; + }, + create: async (props: Record) => { + calls.push({ method: "tabs.create", props }); + return { id: 20, windowId: props["windowId"], url: props["url"], active: props["active"] }; + }, + onCreated: { addListener() {}, removeListener() {} }, + onUpdated: { + addListener(listener: (id: number, change: { status: string }, tab: { url?: string }) => void) { + listener(20, { status: "complete" }, { url: "http://127.0.0.1:4000/" }); + }, + removeListener() {}, + }, + }, + windows: { + getAll: async () => windows, + getLastFocused: async () => windows.find((win) => win["focused"]) ?? windows[0], + update: async () => { + calls.push({ method: "windows.update" }); + }, + }, + permissions: { contains: async () => true }, + scripting: { + executeScript: async () => [{ result: { title: "Hi", headings: [{ level: 1, text: "Hi" }], excerpt: "Hello", snapshot: [] } }], + }, + debugger: { attach() { calls.push({ method: "debugger.attach" }); } }, + }; + return { api, calls }; + } + + it("lists normal windows and skips incognito without touching the debugger or focus", async () => { + const { api, calls } = apiFor({}, [ + { + id: 1, + focused: true, + type: "normal", + incognito: false, + tabs: [{ id: 4, windowId: 1, url: "http://127.0.0.1:3000/", title: "Local", active: true, discarded: false, lastAccessed: 5 }], + }, + { id: 2, focused: false, type: "normal", incognito: true, tabs: [{ id: 9, windowId: 2, url: "https://secret.example/", title: "Secret" }] }, + ]); + const loaded = loadExtension(api); + loaded.BTMCP_SAFETY.install(api); + let result: Record = {}; + await loaded.BTMCP_TABS.list(api, { requestId: "1" }, (_id, payload) => { + result = payload; + }); + expect(result["ok"]).toBe(true); + const windows = result["windows"] as { tabs: { chromeTabId: number }[] }[]; + expect(windows).toHaveLength(1); + expect(windows[0]?.tabs[0]?.chromeTabId).toBe(4); + expect(JSON.stringify(result)).not.toContain("secret.example"); + expect(calls).toEqual([]); + expect((result["safety"] as { debuggerCalls: number; focusChanges: number }).debuggerCalls).toBe(0); + }); + + it("refuses background navigate outside the visible window and does not activate a tab", async () => { + const { api, calls } = apiFor( + { 8: { id: 8, windowId: 2, url: "http://127.0.0.1:3000/", discarded: false, incognito: false } }, + [ + { id: 1, focused: true, type: "normal", incognito: false, tabs: [] }, + { id: 2, focused: false, type: "normal", incognito: false, tabs: [] }, + ] + ); + const loaded = loadExtension(api); + loaded.BTMCP_SAFETY.install(api); + let result: Record = {}; + await loaded.BTMCP_TABS.navigateChrome( + api, + { requestId: "2", chromeTabId: 8, url: "http://127.0.0.1:3000/next", approvedUrl: "http://127.0.0.1:3000/" }, + (_id, payload) => { + result = payload; + } + ); + expect(result["ok"]).toBe(false); + expect(String(result["error"])).toMatch(/visible window/); + expect(calls).toEqual([]); + }); + + it("opens a background tab in the visible window with active false", async () => { + const { api, calls } = apiFor({}, [{ id: 1, focused: true, type: "normal", incognito: false, tabs: [] }]); + const loaded = loadExtension(api); + loaded.BTMCP_SAFETY.install(api); + let result: Record = {}; + await loaded.BTMCP_TABS.navigateChrome( + api, + { requestId: "3", create: true, url: "http://127.0.0.1:4000/" }, + (_id, payload) => { + result = payload; + } + ); + expect(result["ok"]).toBe(true); + expect(result["created"]).toBe(true); + expect(calls).toEqual([{ method: "tabs.create", props: { url: "http://127.0.0.1:4000/", active: false, windowId: 1 } }]); + expect(calls.some((call) => call.method === "debugger.attach" || call.method === "windows.update")).toBe(false); + }); + + it("reports an asleep tab without reading or reloading it", async () => { + const { api, calls } = apiFor( + { 6: { id: 6, url: "http://127.0.0.1:3000/", title: "Sleeping", discarded: true, frozen: false } }, + [] + ); + const loaded = loadExtension(api); + let result: Record = {}; + await loaded.BTMCP_TABS.read( + api, + { requestId: "4", chromeTabId: 6, approvedUrl: "http://127.0.0.1:3000/" }, + (_id, payload) => { + result = payload; + } + ); + const read = result["read"] as { asleep: boolean; skipped: string }; + expect(read.asleep).toBe(true); + expect(read.skipped).toBe("asleep"); + expect(calls.some((call) => call.method === "tabs.update")).toBe(false); + }); + + it("reads loopback pages when permissions.contains is false, and skips other origins", async () => { + const scripts: { world?: string; files?: string[] }[] = []; + const { api } = apiFor( + { + 7: { id: 7, url: "http://127.0.0.1:3000/form", title: "Form", discarded: false, frozen: false }, + 8: { id: 8, url: "https://example.com/", title: "Example", discarded: false, frozen: false }, + }, + [] + ); + (api.permissions as { contains: () => Promise }).contains = async () => false; + api.scripting.executeScript = async (details: { world?: string; files?: string[] }) => { + scripts.push(details); + return [{ result: { title: "Form", headings: [{ level: 1, text: "Soft form" }], excerpt: "Soft form", snapshot: [] } }]; + }; + const loaded = loadExtension(api); + let local: Record = {}; + await loaded.BTMCP_TABS.read(api, { requestId: "5", chromeTabId: 7, approvedUrl: "http://127.0.0.1:3000/form" }, (_id, payload) => { + local = payload; + }); + const read = local["read"] as { headings: { text: string }[]; hostAccess: boolean }; + expect(read.hostAccess).toBe(true); + expect(read.headings[0]?.text).toBe("Soft form"); + expect(scripts[0]).toMatchObject({ world: "ISOLATED", files: ["tab-page.js"] }); + + scripts.length = 0; + let remote: Record = {}; + await loaded.BTMCP_TABS.read(api, { requestId: "6", chromeTabId: 8, approvedUrl: "https://example.com/" }, (_id, payload) => { + remote = payload; + }); + const skipped = remote["read"] as { skipped: string; headings: unknown[] }; + expect(skipped.skipped).toMatch(/host access/); + expect(skipped.headings).toEqual([]); + expect(scripts).toEqual([]); + }); +}); + +describe("soft input in the page", () => { + it("scrubs private details and reports a file picker as needing a real gesture", () => { + const input = { + tagName: "INPUT", + type: "file", + getAttribute: (name: string) => (name === "type" ? "file" : null), + getBoundingClientRect: () => ({ width: 10, height: 10, left: 0, top: 0 }), + closest: () => null, + contains: () => false, + addEventListener() {}, + removeEventListener() {}, + dispatchEvent() {}, + }; + const loaded = loadExtension( + {}, + { + querySelector: () => input, + elementFromPoint: () => input, + } + ); + expect(loaded.btmcpScrubText("user@example.com ghp_abcdefghijklmnopqrstuvwxyz0123456789")).not.toMatch(/user@|ghp_/); + const result = loaded.btmcpSoftAct({ op: "click", selector: "#file" }); + expect(result).toMatchObject({ outcome: "needs a real gesture", reason: "file picker", trusted: false }); + }); + + it("sets an input with the native setter and reports worked", () => { + let stored = ""; + class HTMLInputElement {} + const descriptor = { set: (value: string) => { stored = value; }, configurable: true }; + Object.defineProperty(HTMLInputElement.prototype, "value", descriptor); + const input = { + tagName: "INPUT", + type: "text", + disabled: false, + readOnly: false, + get value() { return stored; }, + set value(next: string) { stored = next; }, + getAttribute: (name: string) => (name === "type" ? "text" : null), + getBoundingClientRect: () => ({ width: 20, height: 10, left: 0, top: 0 }), + closest: () => null, + contains: () => true, + addEventListener() {}, + removeEventListener() {}, + dispatchEvent() {}, + }; + const context = loadExtension( + {}, + { + querySelector: () => input, + elementFromPoint: () => input, + } + ); + (context as unknown as { HTMLInputElement: typeof HTMLInputElement }).HTMLInputElement = HTMLInputElement; + const result = context.btmcpSoftAct({ op: "type", selector: "#name", text: "Ada" }); + expect(result).toMatchObject({ outcome: "worked", reason: null, trusted: false }); + expect(stored).toBe("Ada"); + }); +}); diff --git a/browser-tools-mcp/test/unit/tab-listing.test.ts b/browser-tools-mcp/test/unit/tab-listing.test.ts new file mode 100644 index 00000000..f284dcff --- /dev/null +++ b/browser-tools-mcp/test/unit/tab-listing.test.ts @@ -0,0 +1,115 @@ +import { describe, expect, it } from "vitest"; + +import { defaultGatePolicy } from "../../src/gates/capability"; +import { TAB_COVERAGE } from "../../src/tabs/contract"; +import { + normalizeChromeTabListing, + parseChromeNavigate, + parseSoftInput, +} from "../../src/tabs/listing"; + +describe("normalizeChromeTabListing", () => { + it("drops incognito, excluded origins, and keeps chrome.tabs metadata", () => { + const listing = normalizeChromeTabListing( + { + visibleWindowId: 1, + windows: [ + { + windowId: 1, + focused: true, + type: "normal", + incognito: false, + tabs: [ + { + chromeTabId: 7, + windowId: 1, + title: "Local", + url: "http://127.0.0.1:3000/app", + active: true, + pinned: false, + discarded: true, + frozen: false, + lastAccessed: 100, + audible: false, + status: "complete", + index: 0, + }, + { + chromeTabId: 8, + windowId: 1, + title: "Mail sess_abcdefghijklmnopqrstuvwxyz", + url: "https://excluded.example/inbox?token=ghp_abcdefghijklmnopqrstuvwxyz0123456789", + active: false, + discarded: false, + frozen: true, + lastAccessed: 50, + }, + ], + }, + { + windowId: 2, + focused: false, + type: "normal", + incognito: true, + tabs: [{ chromeTabId: 9, windowId: 2, title: "Private", url: "https://example.com/", active: true }], + }, + ], + }, + { ...defaultGatePolicy(), excludeOrigins: ["https://excluded.example"] } + ); + + expect(listing.coverage).toBe(TAB_COVERAGE); + expect(listing.visibleWindowId).toBe(1); + expect(listing.windows).toHaveLength(1); + expect(listing.windows[0]?.tabs).toHaveLength(1); + expect(listing.windows[0]?.tabs[0]).toMatchObject({ + chromeTabId: 7, + site: "http://127.0.0.1:3000", + discarded: true, + lastAccessed: 100, + active: true, + }); + expect(JSON.stringify(listing)).not.toContain("ghp_"); + expect(JSON.stringify(listing)).not.toContain("Private"); + }); +}); + +describe("tab action results", () => { + it("refuses a navigation that attached the debugger or changed focus", () => { + expect(() => + parseChromeNavigate("http://127.0.0.1/", { + chromeTabId: 3, + visibleWindowId: 1, + finalUrl: "http://127.0.0.1/", + safety: { debuggerCalls: 1, focusChanges: 0 }, + }) + ).toThrow(/debugger or change focus/); + }); + + it("never reports a soft action as trusted", () => { + expect( + parseSoftInput(4, { + outcome: "worked", + reason: null, + detail: "Value set", + trusted: true, + safety: { debuggerCalls: 0, focusChanges: 0 }, + }) + ).toEqual({ + chromeTabId: 4, + outcome: "worked", + reason: null, + detail: "Value set", + trusted: false, + }); + + expect(() => + parseSoftInput(4, { + outcome: "needs a real gesture", + reason: "made up", + detail: "", + safety: { debuggerCalls: 0, focusChanges: 0 }, + }) + ).toThrow(/without a reason/); + }); +}); diff --git a/chrome-extension/gates.js b/chrome-extension/gates.js index bba82090..0ffd379d 100644 --- a/chrome-extension/gates.js +++ b/chrome-extension/gates.js @@ -52,6 +52,9 @@ var BTMCP_GATES = (function () { if (input.action === "listTabs") { return { allowed: true, reason: "allowed" }; } + if (input.action === "navigate" && input.creatingTab === true) { + return { allowed: true, reason: "allowed" }; + } var liveOrigin = originOf(input.liveUrl); var approvedOrigin = originOf(input.approvedUrl); if (!liveOrigin || !approvedOrigin) { diff --git a/chrome-extension/manifest.json b/chrome-extension/manifest.json index e3500977..4026242b 100644 --- a/chrome-extension/manifest.json +++ b/chrome-extension/manifest.json @@ -11,7 +11,7 @@ "service_worker": "worker.js" }, "devtools_page": "devtools.html", - "permissions": ["debugger", "storage", "tabs", "alarms"], + "permissions": ["debugger", "storage", "tabs", "alarms", "scripting"], "optional_permissions": ["cookies"], "host_permissions": ["http://127.0.0.1/*", "http://localhost/*"], "optional_host_permissions": [""], diff --git a/chrome-extension/popup.html b/chrome-extension/popup.html index a2ff9fa4..cbf782a6 100644 --- a/chrome-extension/popup.html +++ b/chrome-extension/popup.html @@ -99,6 +99,14 @@

BrowserTools MCP

One http(s) origin per line. Listed origins are never acted on.

+

+ +

+

+ Reading a tab and soft input need host access for that site. Local pages are already allowed. + This asks Chrome for access. It does not hide the debugging banner, and the debugging banner + stays off unless a DevTools capture attaches the debugger. +

diff --git a/chrome-extension/popup.js b/chrome-extension/popup.js index c6191ecf..86b8e7ee 100644 --- a/chrome-extension/popup.js +++ b/chrome-extension/popup.js @@ -12,6 +12,7 @@ var api = typeof globalThis.browser !== "undefined" ? globalThis.browser : globalThis.chrome; var allow = document.getElementById("allowPageActions"); var exclude = document.getElementById("excludeOrigins"); + var grant = document.getElementById("grantHostAccess"); var saved = document.getElementById("saved"); function storageGet(area, key) { @@ -86,6 +87,21 @@ await notifyWorker(); }); + if (grant) { + grant.addEventListener("click", function () { + var request = api.permissions.request({ origins: [""] }); + Promise.resolve(request) + .then(function (granted) { + saved.textContent = granted + ? "Host access granted for open pages." + : "Host access was not granted."; + }) + .catch(function () { + saved.textContent = "Host access was not granted."; + }); + }); + } + document.documentElement.dataset.ready = "true"; } diff --git a/chrome-extension/tab-actions.js b/chrome-extension/tab-actions.js new file mode 100644 index 00000000..13d9ee4c --- /dev/null +++ b/chrome-extension/tab-actions.js @@ -0,0 +1,560 @@ +/** + * chrome.tabs actions for the service worker. + * + * List, read, background navigate, and soft click/type. No debugger API. + * Navigation always passes active: false and never focuses a window. + * Background navigate stays in the visible window. + */ +var BTMCP_TABS = (function () { + function storageGet(area, keys) { + return new Promise(function (resolve) { + try { + area.get(keys, function (stored) { + resolve(stored || {}); + }); + } catch (error) { + resolve({}); + } + }); + } + + async function readHumanState(chromeApi) { + var session = await storageGet(chromeApi.storage.session, [BTMCP_GATES.POPUP_SWITCH_KEY]); + var local = await storageGet(chromeApi.storage.local, [BTMCP_GATES.EXCLUDE_KEY]); + var exclude = local[BTMCP_GATES.EXCLUDE_KEY]; + return { + popupEnabled: session[BTMCP_GATES.POPUP_SWITCH_KEY] === true, + excludeOrigins: Array.isArray(exclude) + ? exclude.filter(function (entry) { + return typeof entry === "string"; + }) + : [], + }; + } + + function excluded(url, list) { + var origin = BTMCP_GATES.originOf(url); + if (!origin) return false; + for (var i = 0; i < list.length; i++) { + if (BTMCP_GATES.originOf(list[i]) === origin) return true; + } + return false; + } + + function fail(respond, requestId, type, error) { + respond(requestId, { type: type, ok: false, error: error instanceof Error ? error.message : String(error) }); + } + + function delta(before) { + var after = BTMCP_SAFETY.snapshot(); + return { + debuggerCalls: after.debuggerCalls - before.debuggerCalls, + focusChanges: after.focusChanges - before.focusChanges, + }; + } + + function serializeTab(tab, windowId) { + return { + chromeTabId: tab.id, + windowId: typeof tab.windowId === "number" ? tab.windowId : windowId, + title: typeof tab.title === "string" ? tab.title : "", + url: typeof tab.url === "string" ? tab.url : "", + active: tab.active === true, + pinned: tab.pinned === true, + discarded: tab.discarded === true, + frozen: tab.frozen === true, + lastAccessed: typeof tab.lastAccessed === "number" ? tab.lastAccessed : null, + audible: tab.audible === true, + status: typeof tab.status === "string" ? tab.status : "", + index: typeof tab.index === "number" ? tab.index : 0, + incognito: tab.incognito === true, + }; + } + + async function visibleWindowId(chromeApi, already) { + var windows = already || (await chromeApi.windows.getAll({ populate: false })); + var i; + for (i = 0; i < windows.length; i++) { + var win = windows[i]; + if (win && win.focused === true && win.incognito !== true && (win.type === "normal" || !win.type)) { + return win.id; + } + } + try { + var last = await chromeApi.windows.getLastFocused({ windowTypes: ["normal"] }); + if (last && last.incognito !== true && typeof last.id === "number") return last.id; + } catch (error) { + /* fall through to the first normal window */ + } + for (i = 0; i < windows.length; i++) { + if (windows[i] && windows[i].incognito !== true && windows[i].type === "normal") return windows[i].id; + } + return null; + } + + function unsupportedPage(url) { + if (!url) return "missing url"; + var lower = url.toLowerCase(); + if ( + lower.indexOf("chrome://") === 0 || + lower.indexOf("chrome-extension://") === 0 || + lower.indexOf("edge://") === 0 || + lower.indexOf("about:") === 0 || + lower.indexOf("devtools://") === 0 + ) { + return "unsupported page"; + } + if (lower.indexOf("https://chrome.google.com/webstore") === 0 || lower.indexOf("https://chromewebstore.google.com") === 0) { + return "web store"; + } + if (/\.pdf($|\?)/i.test(lower)) return "pdf viewer"; + if (!/^https?:\/\//i.test(url)) return "unsupported page"; + return null; + } + + /** + * chrome.permissions.contains only reports optional grants. The manifest + * already allows http loopback, and that must count as granted. + */ + function manifestCovers(url) { + try { + var parsed = new URL(url); + return parsed.protocol === "http:" && (parsed.hostname === "127.0.0.1" || parsed.hostname === "localhost"); + } catch (error) { + return false; + } + } + + async function hostGranted(chromeApi, url) { + if (manifestCovers(url)) return true; + try { + var parsed = new URL(url); + var candidates = ["", parsed.origin + "/*"]; + if (parsed.port) candidates.push(parsed.protocol + "//" + parsed.hostname + "/*"); + for (var i = 0; i < candidates.length; i++) { + var granted = await chromeApi.permissions.contains({ origins: [candidates[i]] }); + if (granted) return true; + } + return false; + } catch (error) { + return false; + } + } + + /** + * executeScript serializes `func` alone. Helpers live in tab-page.js, so + * that file is injected into the same world before the call. + */ + async function runInTab(chromeApi, tabId, world, entry, args) { + await chromeApi.scripting.executeScript({ + target: { tabId: tabId }, + world: world, + files: ["tab-page.js"], + }); + var details = { + target: { tabId: tabId }, + world: world, + func: entry, + }; + if (args) details.args = args; + return chromeApi.scripting.executeScript(details); + } + + function readPageEntry() { + return btmcpReadPage(); + } + + function softActEntry(command) { + return btmcpSoftAct(command); + } + + function watchOpened(chromeApi) { + var opened = []; + function onCreated(tab) { + if (!tab || typeof tab.id !== "number") return; + opened.push({ + chromeTabId: tab.id, + url: tab.pendingUrl || tab.url || "", + windowId: typeof tab.windowId === "number" ? tab.windowId : 0, + active: tab.active === true, + }); + } + if (chromeApi.tabs.onCreated && chromeApi.tabs.onCreated.addListener) { + chromeApi.tabs.onCreated.addListener(onCreated); + } + return { + stop: function () { + if (chromeApi.tabs.onCreated && chromeApi.tabs.onCreated.removeListener) { + chromeApi.tabs.onCreated.removeListener(onCreated); + } + }, + list: function (selfId) { + return opened.filter(function (tab) { + return tab.chromeTabId !== selfId; + }); + }, + }; + } + + function waitForTabUrl(chromeApi, tabId, timeoutMs) { + return new Promise(function (resolve) { + var done = false; + function finish(url) { + if (done) return; + done = true; + clearTimeout(timer); + if (chromeApi.tabs.onUpdated) chromeApi.tabs.onUpdated.removeListener(onUpdated); + resolve(url || ""); + } + var timer = setTimeout(function () { + chromeApi.tabs + .get(tabId) + .then(function (tab) { + finish(tab && tab.url ? tab.url : ""); + }) + .catch(function () { + finish(""); + }); + }, timeoutMs); + function onUpdated(updatedId, changeInfo, tab) { + if (String(updatedId) !== String(tabId)) return; + if (changeInfo.status === "complete" && tab && tab.url) finish(tab.url); + } + if (chromeApi.tabs.onUpdated) chromeApi.tabs.onUpdated.addListener(onUpdated); + }); + } + + async function list(chromeApi, message, respond) { + var state = await readHumanState(chromeApi); + var gate = BTMCP_GATES.confirmBeforeAct({ + action: "listTabs", + popupEnabled: state.popupEnabled, + panelEnabled: false, + hideBanner: message && message.hideBanner === true, + }); + if (!gate.allowed) { + fail(respond, message.requestId, "chrome-tabs-result", gate.reason); + return; + } + var before = BTMCP_SAFETY.snapshot(); + try { + var all = await chromeApi.windows.getAll({ populate: true }); + var visible = await visibleWindowId(chromeApi, all); + var windows = []; + for (var i = 0; i < all.length; i++) { + var win = all[i]; + if (!win || win.incognito === true) continue; + if (win.type && win.type !== "normal" && win.type !== "popup") continue; + var tabs = []; + var raw = win.tabs || []; + for (var t = 0; t < raw.length; t++) { + var tab = raw[t]; + if (!tab || tab.incognito === true || typeof tab.id !== "number") continue; + if (excluded(tab.url || "", state.excludeOrigins)) continue; + tabs.push(serializeTab(tab, win.id)); + } + windows.push({ + windowId: win.id, + focused: win.focused === true, + type: win.type || "normal", + incognito: false, + tabs: tabs, + }); + } + respond(message.requestId, { + type: "chrome-tabs-result", + ok: true, + visibleWindowId: visible, + windows: windows, + safety: delta(before), + }); + } catch (error) { + fail(respond, message.requestId, "chrome-tabs-result", error); + } + } + + async function navigateConnected(chromeApi, message, respond) { + var tabId = message.tabId; + var url = message.url; + if ((typeof tabId !== "number" && typeof tabId !== "string") || typeof url !== "string" || !url) { + fail(respond, message.requestId, "navigate-result", "tabId and url are required"); + return; + } + var beforeSafety = BTMCP_SAFETY.snapshot(); + try { + var before = await chromeApi.tabs.get(tabId); + var wasDiscarded = Boolean(before && before.discarded); + await BTMCP_SAFETY.tabsUpdate(chromeApi, tabId, { url: url, active: false }); + var finalUrl = await waitForTabUrl(chromeApi, tabId, 30000); + if (!finalUrl) { + var after = await chromeApi.tabs.get(tabId); + finalUrl = after && after.url ? after.url : url; + } + respond(message.requestId, { + type: "navigate-result", + ok: true, + finalUrl: finalUrl, + wasDiscarded: wasDiscarded, + safety: delta(beforeSafety), + }); + } catch (error) { + fail(respond, message.requestId, "navigate-result", error); + } + } + + async function navigateChrome(chromeApi, message, respond) { + var url = message.url; + if (typeof url !== "string" || !url) { + fail(respond, message.requestId, "navigate-chrome-result", "url is required"); + return; + } + var state = await readHumanState(chromeApi); + var creating = message.create === true || message.chromeTabId == null; + var beforeSafety = BTMCP_SAFETY.snapshot(); + var watcher = watchOpened(chromeApi); + try { + var visible = await visibleWindowId(chromeApi); + if (typeof visible !== "number") { + throw new Error("No visible window to navigate in."); + } + if (creating) { + var createdGate = BTMCP_GATES.confirmBeforeAct({ + action: "navigate", + popupEnabled: state.popupEnabled, + panelEnabled: false, + creatingTab: true, + hideBanner: message.hideBanner === true, + }); + if (!createdGate.allowed) throw new Error(createdGate.reason); + var created = await BTMCP_SAFETY.tabsCreate(chromeApi, { + windowId: visible, + url: url, + active: false, + }); + var createdId = created && created.id; + if (typeof createdId !== "number") throw new Error("The browser did not return a tab id."); + var createdUrl = await waitForTabUrl(chromeApi, createdId, 30000); + respond(message.requestId, { + type: "navigate-chrome-result", + ok: true, + chromeTabId: createdId, + finalUrl: createdUrl || url, + wasDiscarded: false, + created: true, + visibleWindowId: visible, + openedTabs: watcher.list(createdId), + safety: delta(beforeSafety), + }); + return; + } + + var chromeTabId = message.chromeTabId; + if (typeof chromeTabId !== "number") throw new Error("chromeTabId must be a chrome.tabs id from listTabs."); + var before = await chromeApi.tabs.get(chromeTabId); + if (!before) throw new Error("Tab not found."); + if (before.incognito === true) throw new Error("Incognito is skipped."); + if (before.windowId !== visible) { + throw new Error( + "Background navigate stays limited to the visible window. This tab is in another window." + ); + } + var liveGate = BTMCP_GATES.confirmBeforeAct({ + action: "navigate", + popupEnabled: state.popupEnabled, + panelEnabled: false, + approvedUrl: message.approvedUrl, + liveUrl: before.url || "", + hideBanner: message.hideBanner === true, + }); + if (!liveGate.allowed) throw new Error(liveGate.reason); + var wasDiscarded = before.discarded === true; + await BTMCP_SAFETY.tabsUpdate(chromeApi, chromeTabId, { url: url, active: false }); + var finalUrl = await waitForTabUrl(chromeApi, chromeTabId, 30000); + respond(message.requestId, { + type: "navigate-chrome-result", + ok: true, + chromeTabId: chromeTabId, + finalUrl: finalUrl || url, + wasDiscarded: wasDiscarded, + created: false, + visibleWindowId: visible, + openedTabs: watcher.list(chromeTabId), + safety: delta(beforeSafety), + }); + } catch (error) { + fail(respond, message.requestId, "navigate-chrome-result", error); + } finally { + watcher.stop(); + } + } + + function emptyRead(tab, extra) { + return Object.assign( + { + chromeTabId: tab.id, + url: typeof tab.url === "string" ? tab.url : "", + title: typeof tab.title === "string" ? tab.title : "", + asleep: tab.discarded === true, + frozen: tab.frozen === true, + skipped: null, + headings: [], + excerpt: "", + snapshot: [], + hostAccess: false, + }, + extra || {} + ); + } + + async function read(chromeApi, message, respond) { + var chromeTabId = message.chromeTabId; + if (typeof chromeTabId !== "number") { + fail(respond, message.requestId, "chrome-tab-read-result", "chromeTabId must be a chrome.tabs id from listTabs."); + return; + } + var state = await readHumanState(chromeApi); + var beforeSafety = BTMCP_SAFETY.snapshot(); + try { + var tab = await chromeApi.tabs.get(chromeTabId); + if (!tab) throw new Error("Tab not found."); + if (tab.incognito === true) throw new Error("Incognito is skipped."); + if (excluded(tab.url || "", state.excludeOrigins)) throw new Error("origin is excluded"); + var gate = BTMCP_GATES.confirmBeforeAct({ + action: "readTab", + popupEnabled: state.popupEnabled, + panelEnabled: false, + approvedUrl: message.approvedUrl, + liveUrl: tab.url || "", + hideBanner: message.hideBanner === true, + }); + if (!gate.allowed) throw new Error(gate.reason); + if (tab.discarded === true) { + respond(message.requestId, { + type: "chrome-tab-read-result", + ok: true, + safety: delta(beforeSafety), + read: emptyRead(tab, { asleep: true, skipped: "asleep", hostAccess: true }), + }); + return; + } + if (tab.frozen === true) { + respond(message.requestId, { + type: "chrome-tab-read-result", + ok: true, + safety: delta(beforeSafety), + read: emptyRead(tab, { frozen: true, skipped: "frozen", hostAccess: true }), + }); + return; + } + var blocked = unsupportedPage(tab.url || ""); + if (blocked) { + respond(message.requestId, { + type: "chrome-tab-read-result", + ok: true, + safety: delta(beforeSafety), + read: emptyRead(tab, { skipped: blocked, hostAccess: false }), + }); + return; + } + var granted = await hostGranted(chromeApi, tab.url); + if (!granted) { + respond(message.requestId, { + type: "chrome-tab-read-result", + ok: true, + safety: delta(beforeSafety), + read: emptyRead(tab, { skipped: "host access is not granted", hostAccess: false }), + }); + return; + } + var injected = await runInTab(chromeApi, chromeTabId, "ISOLATED", readPageEntry); + var page = injected && injected[0] && injected[0].result ? injected[0].result : {}; + respond(message.requestId, { + type: "chrome-tab-read-result", + ok: true, + safety: delta(beforeSafety), + read: emptyRead(tab, { + asleep: false, + frozen: false, + skipped: null, + hostAccess: true, + title: page.title || tab.title || "", + headings: Array.isArray(page.headings) ? page.headings : [], + excerpt: typeof page.excerpt === "string" ? page.excerpt : "", + snapshot: Array.isArray(page.snapshot) ? page.snapshot : [], + }), + }); + } catch (error) { + fail(respond, message.requestId, "chrome-tab-read-result", error); + } + } + + async function soft(chromeApi, message, respond) { + var chromeTabId = message.chromeTabId; + var selector = message.selector; + var op = message.op === "type" ? "type" : "click"; + if (typeof chromeTabId !== "number") { + fail(respond, message.requestId, "soft-input-result", "chromeTabId must be a chrome.tabs id from listTabs."); + return; + } + if (typeof selector !== "string" || !selector || selector.length > 500) { + fail(respond, message.requestId, "soft-input-result", "selector is required"); + return; + } + if (op === "type" && (typeof message.text !== "string" || message.text.length > 20000)) { + fail(respond, message.requestId, "soft-input-result", "text is required"); + return; + } + var state = await readHumanState(chromeApi); + var beforeSafety = BTMCP_SAFETY.snapshot(); + try { + var tab = await chromeApi.tabs.get(chromeTabId); + if (!tab) throw new Error("Tab not found."); + if (tab.incognito === true) throw new Error("Incognito is skipped."); + if (tab.discarded === true) throw new Error("Tab is asleep. It was not reloaded."); + if (tab.frozen === true) throw new Error("Tab is frozen and was skipped."); + var blocked = unsupportedPage(tab.url || ""); + if (blocked) throw new Error(blocked); + var gate = BTMCP_GATES.confirmBeforeAct({ + action: op === "type" ? "softType" : "softClick", + popupEnabled: state.popupEnabled, + panelEnabled: false, + approvedUrl: message.approvedUrl, + liveUrl: tab.url || "", + hideBanner: message.hideBanner === true, + }); + if (!gate.allowed) throw new Error(gate.reason); + var granted = await hostGranted(chromeApi, tab.url); + if (!granted) throw new Error("host access is not granted"); + var injected = await runInTab(chromeApi, chromeTabId, "MAIN", softActEntry, [ + { op: op, selector: selector, text: message.text || "", submit: message.submit === true }, + ]); + var result = injected && injected[0] ? injected[0].result : null; + if (!result || (result.outcome !== "worked" && result.outcome !== "needs a real gesture")) { + throw new Error("Soft input did not report an outcome."); + } + if (result.outcome === "needs a real gesture" && typeof result.reason !== "string") { + throw new Error("Soft input refused without a reason."); + } + respond(message.requestId, { + type: "soft-input-result", + ok: true, + chromeTabId: chromeTabId, + outcome: result.outcome, + reason: result.outcome === "worked" ? null : result.reason, + detail: typeof result.detail === "string" ? result.detail : "", + trusted: false, + safety: delta(beforeSafety), + }); + } catch (error) { + fail(respond, message.requestId, "soft-input-result", error); + } + } + + return { + list: list, + read: read, + soft: soft, + navigateChrome: navigateChrome, + navigateConnected: navigateConnected, + }; +})(); diff --git a/chrome-extension/tab-page.js b/chrome-extension/tab-page.js new file mode 100644 index 00000000..c81e5cb6 --- /dev/null +++ b/chrome-extension/tab-page.js @@ -0,0 +1,334 @@ +/** + * Runs inside a tab via chrome.scripting.executeScript. + * + * btmcpReadPage stays in the isolated world. btmcpSoftAct runs in the page's + * main world so the native value setter and execCommand reach React, Vue, and + * rich editors. Neither function calls the debugger API or changes window focus. + */ + +function btmcpScrubText(value) { + var text = String(value == null ? "" : value); + text = text.replace(/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi, "[redacted]"); + text = text.replace(/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}\b/g, "[redacted]"); + text = text.replace(/\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{10,}\b/g, "[redacted]"); + text = text.replace(/\bgh[pousr]_[A-Za-z0-9]{16,}\b/g, "[redacted]"); + text = text.replace(/\bgithub_pat_[A-Za-z0-9_]{16,}\b/g, "[redacted]"); + text = text.replace(/\b(?:bearer\s+)\S+/gi, "bearer [redacted]"); + text = text.replace(/\b\d{13,19}\b/g, "[redacted]"); + return text; +} + +function btmcpSkipText(element) { + var tag = element && element.tagName; + return tag === "SCRIPT" || tag === "STYLE" || tag === "NOSCRIPT" || tag === "TEXTAREA" || tag === "INPUT" || tag === "SELECT"; +} + +function btmcpReadPage() { + var headings = []; + var nodes = document.querySelectorAll("h1, h2, h3, h4, h5, h6"); + var limit = Math.min(nodes.length, 30); + for (var i = 0; i < limit; i++) { + var heading = nodes[i]; + var level = Number(heading.tagName.slice(1)); + var text = btmcpScrubText((heading.innerText || heading.textContent || "").replace(/\s+/g, " ").trim()).slice(0, 200); + if (text) headings.push({ level: level, text: text }); + } + + var excerpt = ""; + var walker = document.createTreeWalker(document.body || document.documentElement, NodeFilter.SHOW_TEXT, { + acceptNode: function (node) { + var parent = node.parentElement; + if (!parent || btmcpSkipText(parent) || parent.closest("script, style, textarea, input, select")) { + return NodeFilter.FILTER_REJECT; + } + return NodeFilter.FILTER_ACCEPT; + }, + }); + var chunk; + while ((chunk = walker.nextNode())) { + var piece = (chunk.textContent || "").replace(/\s+/g, " ").trim(); + if (!piece) continue; + excerpt = excerpt ? excerpt + " " + piece : piece; + if (excerpt.length >= 800) break; + } + excerpt = btmcpScrubText(excerpt).slice(0, 800); + + var roleByTag = { + A: "link", + BUTTON: "button", + H1: "heading", + H2: "heading", + H3: "heading", + H4: "heading", + H5: "heading", + H6: "heading", + INPUT: "textbox", + TEXTAREA: "textbox", + SELECT: "combobox", + NAV: "navigation", + MAIN: "main", + FORM: "form", + IMG: "img", + }; + var snapshot = []; + + function nodeName(element) { + var aria = element.getAttribute && element.getAttribute("aria-label"); + if (aria) return btmcpScrubText(aria).slice(0, 80); + var tag = element.tagName; + if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") { + if ((element.getAttribute("type") || "").toLowerCase() === "password") return "password"; + var placeholder = element.getAttribute("placeholder"); + if (placeholder) return btmcpScrubText(placeholder).slice(0, 80); + return element.getAttribute("name") || element.id || ""; + } + var raw = (element.innerText || element.textContent || "").replace(/\s+/g, " ").trim(); + return btmcpScrubText(raw).slice(0, 80); + } + + function walk(element, depth) { + if (!element || snapshot.length >= 60 || depth > 4) return; + var tag = element.tagName; + var role = (element.getAttribute && element.getAttribute("role")) || roleByTag[tag]; + if (role && tag !== "SCRIPT" && tag !== "STYLE") { + snapshot.push({ depth: depth, role: role, name: nodeName(element) }); + } + var children = element.children || []; + for (var c = 0; c < children.length; c++) walk(children[c], depth + 1); + } + + walk(document.body || document.documentElement, 0); + + return { + title: btmcpScrubText(document.title || "").slice(0, 200), + headings: headings, + excerpt: excerpt, + snapshot: snapshot, + }; +} + +function btmcpGesture(reason, detail) { + return { outcome: "needs a real gesture", reason: reason, detail: detail, trusted: false }; +} + +function btmcpWorked(detail) { + return { outcome: "worked", reason: null, detail: detail, trusted: false }; +} + +function btmcpLabel(element) { + var aria = (element.getAttribute && element.getAttribute("aria-label")) || ""; + var text = (element.innerText || element.textContent || "").replace(/\s+/g, " ").trim(); + return (aria + " " + text).trim(); +} + +function btmcpSoftAct(command) { + var op = command && command.op; + var selector = command && command.selector; + if (typeof selector !== "string" || !selector) { + return btmcpGesture("UI that needs the page drawn", "A selector is required."); + } + var element; + try { + element = document.querySelector(selector); + } catch (error) { + return btmcpGesture("UI that needs the page drawn", "The selector is not valid."); + } + if (!element) { + return btmcpGesture("UI that needs the page drawn", "No element matches that selector."); + } + + var host = (location.hostname || "").toLowerCase(); + if (host === "docs.google.com" || host === "sheets.google.com" || host === "slides.google.com") { + return btmcpGesture("Google Docs or canvas app", "Google Docs does not accept untrusted input."); + } + if (element.tagName === "CANVAS" || (element.closest && element.closest("canvas"))) { + return btmcpGesture("Google Docs or canvas app", "Canvas content needs the page drawn and a real gesture."); + } + + var type = ((element.getAttribute && element.getAttribute("type")) || element.type || "").toLowerCase(); + if (type === "file" || (element.closest && element.closest("input[type='file']"))) { + return btmcpGesture("file picker", "A file picker needs a real gesture."); + } + + var label = btmcpLabel(element); + if (/\b(copy|paste|cut)\b/i.test(label) || /clipboard/i.test(String((element.getAttribute && element.getAttribute("onclick")) || ""))) { + return btmcpGesture("clipboard", "Clipboard access needs a real gesture."); + } + if (/\bfull\s*screen\b/i.test(label) || /requestFullscreen/.test(String((element.getAttribute && element.getAttribute("onclick")) || ""))) { + return btmcpGesture("fullscreen", "Fullscreen needs a real gesture."); + } + if (element.tagName === "A" && String(element.getAttribute("target") || "").toLowerCase() === "_blank") { + return btmcpGesture("popup", "Opening another tab or window needs a real gesture."); + } + + var bot = element.closest + ? element.closest(".g-recaptcha, .cf-turnstile, #px-captcha, iframe") + : null; + if (bot) { + var src = (bot.getAttribute && bot.getAttribute("src")) || ""; + var botClass = String(bot.className || ""); + if ( + bot.id === "px-captcha" || + botClass.indexOf("g-recaptcha") !== -1 || + botClass.indexOf("cf-turnstile") !== -1 || + /recaptcha|hcaptcha|challenges\.cloudflare|turnstile/i.test(src) + ) { + return btmcpGesture("anti-bot check", "An anti-bot check covers this control."); + } + } + + var rect = element.getBoundingClientRect ? element.getBoundingClientRect() : { width: 0, height: 0, left: 0, top: 0 }; + if (!rect || rect.width <= 0 || rect.height <= 0) { + return btmcpGesture("UI that needs the page drawn", "The element has no box."); + } + var x = rect.left + rect.width / 2; + var y = rect.top + rect.height / 2; + var top = document.elementFromPoint ? document.elementFromPoint(x, y) : element; + if (!top || (top !== element && !element.contains(top) && !(top.contains && top.contains(element)))) { + return btmcpGesture("UI that needs the page drawn", "Another element covers the target."); + } + + if (op === "type") return btmcpTypeInto(element, command.text == null ? "" : String(command.text), command.submit === true); + if (op === "click") return btmcpClick(element); + return btmcpGesture("UI that needs the page drawn", "Unknown soft action."); +} + +function btmcpFire(element, type, x, y) { + var pointer = type.indexOf("pointer") === 0; + var Ctor = pointer && typeof PointerEvent === "function" ? PointerEvent : MouseEvent; + element.dispatchEvent( + new Ctor(type, { + bubbles: true, + cancelable: true, + clientX: x, + clientY: y, + button: 0, + view: window, + }) + ); +} + +function btmcpClick(element) { + var rect = element.getBoundingClientRect(); + var x = rect.left + rect.width / 2; + var y = rect.top + rect.height / 2; + var form = element.closest ? element.closest("form") : null; + var inputType = ((element.getAttribute && element.getAttribute("type")) || element.type || "").toLowerCase(); + var isSubmit = + Boolean(form) && + (inputType === "submit" || + (element.tagName === "BUTTON" && inputType !== "button" && inputType !== "reset")); + + if (element.tagName === "A" && element.href) { + return btmcpGesture("the site checks isTrusted", "An untrusted click does not follow a link."); + } + if (inputType === "checkbox" || inputType === "radio") { + return btmcpGesture("the site checks isTrusted", "An untrusted click does not toggle this control."); + } + + var saw = false; + function mark() { + saw = true; + } + element.addEventListener("click", mark); + btmcpFire(element, "pointerdown", x, y); + btmcpFire(element, "mousedown", x, y); + btmcpFire(element, "pointerup", x, y); + btmcpFire(element, "mouseup", x, y); + btmcpFire(element, "click", x, y); + element.removeEventListener("click", mark); + + if (isSubmit) { + var submitted = false; + function onSubmit() { + submitted = true; + } + form.addEventListener("submit", onSubmit); + try { + form.requestSubmit(element); + } catch (error) { + form.removeEventListener("submit", onSubmit); + return btmcpGesture("the site checks isTrusted", "requestSubmit did not run."); + } + form.removeEventListener("submit", onSubmit); + if (submitted) return btmcpWorked("Form submitted with requestSubmit."); + return btmcpGesture("the site checks isTrusted", "requestSubmit did not fire submit."); + } + + if (saw) return btmcpWorked("Untrusted click was delivered to the element."); + return btmcpGesture("the site checks isTrusted", "The element did not receive the click."); +} + +function btmcpSetNativeValue(element, text) { + var proto = element.tagName === "TEXTAREA" ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype; + var descriptor = Object.getOwnPropertyDescriptor(proto, "value"); + if (descriptor && descriptor.set) descriptor.set.call(element, text); + else element.value = text; + element.dispatchEvent(new Event("input", { bubbles: true })); + element.dispatchEvent(new Event("change", { bubbles: true })); +} + +function btmcpFindEditor(element) { + if (element.isContentEditable) return element; + if (element.closest) { + return element.closest("[contenteditable='true'], .ProseMirror, .lexical-editor, [data-lexical-editor]"); + } + return null; +} + +function btmcpMaybeSubmit(element, submit) { + if (!submit) return null; + var form = element.closest ? element.closest("form") : null; + if (!form || typeof form.requestSubmit !== "function") { + return btmcpGesture("the site checks isTrusted", "The text was entered but there is no form to submit."); + } + var submitted = false; + function onSubmit() { + submitted = true; + } + form.addEventListener("submit", onSubmit); + try { + form.requestSubmit(); + } catch (error) { + form.removeEventListener("submit", onSubmit); + return btmcpGesture("the site checks isTrusted", "The text was entered but requestSubmit did not run."); + } + form.removeEventListener("submit", onSubmit); + if (!submitted) { + return btmcpGesture("the site checks isTrusted", "The text was entered but the form did not submit."); + } + return null; +} + +function btmcpTypeInto(element, text, submit) { + var inputType = ((element.getAttribute && element.getAttribute("type")) || element.type || "").toLowerCase(); + if (element.tagName === "INPUT" || element.tagName === "TEXTAREA") { + if (inputType === "password") { + return btmcpGesture("the site checks isTrusted", "Password fields are not filled by soft input."); + } + if (element.disabled || element.readOnly) { + return btmcpGesture("the site checks isTrusted", "The field is disabled or read-only."); + } + btmcpSetNativeValue(element, text); + if (element.value !== text) { + return btmcpGesture("the site checks isTrusted", "The value did not stick."); + } + var submitResult = btmcpMaybeSubmit(element, submit); + if (submitResult) return submitResult; + return btmcpWorked(submit ? "Value set and the form submitted." : "Value set with the native setter."); + } + + var editor = btmcpFindEditor(element); + if (!editor) { + return btmcpGesture("UI that needs the page drawn", "This element does not accept text."); + } + if (typeof editor.focus === "function") editor.focus(); + var inserted = typeof document.execCommand === "function" && document.execCommand("insertText", false, text); + var after = editor.textContent || ""; + if (!inserted || after.indexOf(text) === -1) { + return btmcpGesture("the site checks isTrusted", "execCommand did not insert the text."); + } + var editorSubmit = btmcpMaybeSubmit(editor, submit); + if (editorSubmit) return editorSubmit; + return btmcpWorked(submit ? "Text inserted and the form submitted." : "Inserted text with execCommand."); +} diff --git a/chrome-extension/tab-safety.js b/chrome-extension/tab-safety.js new file mode 100644 index 00000000..57134824 --- /dev/null +++ b/chrome-extension/tab-safety.js @@ -0,0 +1,92 @@ +/** + * Counts debugger calls and refuses focus changes. + * + * Wrapping chrome.debugger still calls through, so a real attach would show + * the banner. Tab actions never call it. tabs.update({active:true}) and + * windows.update({focused:true}) throw before the browser sees them. + */ +var BTMCP_SAFETY = (function () { + var debuggerCalls = 0; + var focusChanges = 0; + var installed = false; + + function snapshot() { + return { debuggerCalls: debuggerCalls, focusChanges: focusChanges }; + } + + function noteFocus() { + focusChanges += 1; + } + + function assertNoFocus(props) { + if (!props || typeof props !== "object") return; + if (props.active === true || props.focused === true) { + noteFocus(); + throw new Error("Refusing to change focus."); + } + } + + function install(chromeApi) { + if (installed || !chromeApi) return; + installed = true; + + if (chromeApi.debugger) { + ["attach", "sendCommand", "detach"].forEach(function (name) { + var original = chromeApi.debugger[name]; + if (typeof original !== "function") return; + chromeApi.debugger[name] = function () { + debuggerCalls += 1; + return original.apply(chromeApi.debugger, arguments); + }; + }); + } + + if (chromeApi.tabs && typeof chromeApi.tabs.update === "function") { + var update = chromeApi.tabs.update.bind(chromeApi.tabs); + chromeApi.tabs.update = function (tabId, props) { + assertNoFocus(props); + return update(tabId, props); + }; + } + + if (chromeApi.windows && typeof chromeApi.windows.update === "function") { + var winUpdate = chromeApi.windows.update.bind(chromeApi.windows); + chromeApi.windows.update = function (windowId, props) { + assertNoFocus(props); + return winUpdate(windowId, props); + }; + } + + var root = typeof globalThis !== "undefined" ? globalThis : self; + root.__btmcpSafety = { snapshot: snapshot }; + } + + /** + * Navigation and new tabs must say active: false. Anything else is refused + * and is not forwarded. + */ + function tabsUpdate(chromeApi, tabId, props) { + if (!props || props.active !== false || props.focused === true) { + noteFocus(); + throw new Error("Navigation must pass active: false."); + } + return chromeApi.tabs.update(tabId, { url: props.url, active: false }); + } + + function tabsCreate(chromeApi, props) { + if (!props || props.active !== false || props.focused === true) { + noteFocus(); + throw new Error("A new tab must pass active: false."); + } + var create = { url: props.url, active: false }; + if (typeof props.windowId === "number") create.windowId = props.windowId; + return chromeApi.tabs.create(create); + } + + return { + install: install, + snapshot: snapshot, + tabsUpdate: tabsUpdate, + tabsCreate: tabsCreate, + }; +})(); diff --git a/chrome-extension/worker.js b/chrome-extension/worker.js index cd7420ed..854c1aa1 100644 --- a/chrome-extension/worker.js +++ b/chrome-extension/worker.js @@ -3,11 +3,13 @@ * * Owns the toolbar-popup switch (session storage, so it resets when the * browser quits) and answers capability probes with a tab URL read at that - * moment via chrome.tabs.get. It does not click, type, navigate, or attach - * the debugger; those actions are separate work and must call - * BTMCP_GATES.confirmBeforeAct with a fresh tab read before they run. + * moment via chrome.tabs.get. Tab list, read, background navigate, and soft + * input go through BTMCP_TABS. Those paths do not call the debugger API and do + * not activate a tab or focus a window. DevTools capture stays in devtools.js. */ -importScripts("shared.js", "gates.js"); +importScripts("shared.js", "gates.js", "tab-safety.js", "tab-page.js", "tab-actions.js"); + +BTMCP_SAFETY.install(api); var socket = null; var reconnectTimer = null; @@ -40,16 +42,20 @@ async function readHumanState() { }; } -function send(message) { - if (!socket || socket.readyState !== WebSocket.OPEN) return false; +function sendOn(ws, message) { + if (!ws || ws.readyState !== WebSocket.OPEN) return false; try { - socket.send(JSON.stringify(message)); + ws.send(JSON.stringify(message)); return true; } catch (error) { return false; } } +function send(message) { + return sendOn(socket, message); +} + async function reportState() { var state = await readHumanState(); send({ @@ -68,159 +74,115 @@ function scheduleReconnect() { reconnectDelayMs = Math.min(reconnectDelayMs * 2, 15000); } +var connecting = false; + async function ensureConnected() { - if (closing) return; + if (closing || connecting) return; if (socket && (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING)) { return; } + connecting = true; - var settings = await loadSettings(); - var found = await discoverServer(settings); - if (!found) { - scheduleReconnect(); - return; - } - - var token = ""; try { - var paired = await fetch("http://" + found.host + ":" + found.port + "/.pair", { method: "POST" }); - if (paired.ok) { - var body = await paired.json(); - if (body && typeof body.token === "string") token = body.token; + var settings = await loadSettings(); + var found = await discoverServer(settings); + if (!found) { + scheduleReconnect(); + return; } - } catch (error) { - token = ""; - } - if (!token) { - scheduleReconnect(); - return; - } - var ws; - try { - ws = new WebSocket("ws://" + found.host + ":" + found.port + "/extension-ws", ["browser-tools", token]); - } catch (error) { - scheduleReconnect(); - return; - } - socket = ws; - - ws.onopen = function () { - reconnectDelayMs = 1000; - send({ type: "hello", extensionVersion: "2.0.4", role: "worker" }); - void reportState(); - }; - - ws.onmessage = function (event) { - var message; + var token = ""; try { - message = JSON.parse(event.data); + var paired = await fetch("http://" + found.host + ":" + found.port + "/.pair", { method: "POST" }); + if (paired.ok) { + var body = await paired.json(); + if (body && typeof body.token === "string") token = body.token; + } } catch (error) { + token = ""; + } + if (!token) { + scheduleReconnect(); return; } - if (message && message.type === "capability-probe") { - void answerProbe(message); - } else if (message && message.type === "navigate-tab") { - void navigateTab(message); - } else if (message && message.type === "ping") { - send({ type: "pong", id: message.id }); + + var ws; + try { + ws = new WebSocket("ws://" + found.host + ":" + found.port + "/extension-ws", ["browser-tools", token]); + } catch (error) { + scheduleReconnect(); + return; } - }; + socket = ws; - ws.onclose = function () { - if (socket === ws) socket = null; - scheduleReconnect(); - }; + function reply(requestId, payload) { + sendOn(ws, Object.assign({ requestId: requestId }, payload)); + } - ws.onerror = function () { - /* onclose follows */ - }; + ws.onopen = function () { + reconnectDelayMs = 1000; + sendOn(ws, { type: "hello", extensionVersion: "2.0.4", role: "worker" }); + // State belongs on this socket. reportState() uses the current global + // socket, which a restart may already have replaced. + void readHumanState().then(function (state) { + sendOn(ws, { + type: "capability-state", + popupEnabled: state.popupEnabled, + excludeOrigins: state.excludeOrigins, + }); + }); + }; + + ws.onmessage = function (event) { + var message; + try { + message = JSON.parse(event.data); + } catch (error) { + return; + } + if (message && message.type === "capability-probe") { + void answerProbe(message, reply); + } else if (message && message.type === "navigate-tab") { + void BTMCP_TABS.navigateConnected(api, message, reply); + } else if (message && message.type === "list-chrome-tabs") { + void BTMCP_TABS.list(api, message, reply); + } else if (message && message.type === "navigate-chrome-tab") { + void BTMCP_TABS.navigateChrome(api, message, reply); + } else if (message && message.type === "read-chrome-tab") { + void BTMCP_TABS.read(api, message, reply); + } else if (message && message.type === "soft-input") { + void BTMCP_TABS.soft(api, message, reply); + } else if (message && message.type === "ping") { + sendOn(ws, { type: "pong", id: message.id }); + } + }; + + ws.onclose = function () { + if (socket === ws) socket = null; + scheduleReconnect(); + }; + + ws.onerror = function () { + /* onclose follows */ + }; + } finally { + connecting = false; + } } /** * Reads the switch and the tab again. The URL on the probe message is ignored; * chrome.tabs.get is the only source. */ -function respond(requestId, payload) { - send(Object.assign({ requestId: requestId }, payload)); -} - -function waitForTabUrl(tabId, timeoutMs) { - return new Promise(function (resolve) { - var done = false; - var timer = setTimeout(function () { - if (done) return; - done = true; - api.tabs - .get(tabId) - .then(function (tab) { - resolve(tab && tab.url ? tab.url : ""); - }) - .catch(function () { - resolve(""); - }); - }, timeoutMs); - - function onUpdated(updatedId, changeInfo, tab) { - if (done) return; - if (String(updatedId) !== String(tabId)) return; - if (changeInfo.status === "complete" && tab && tab.url) { - done = true; - clearTimeout(timer); - api.tabs.onUpdated.removeListener(onUpdated); - resolve(tab.url); - } - } - api.tabs.onUpdated.addListener(onUpdated); - }); -} - -async function navigateTab(message) { - var tabId = message.tabId; - var url = message.url; - if ((typeof tabId !== "number" && typeof tabId !== "string") || typeof url !== "string" || !url) { - respond(message.requestId, { - type: "navigate-result", - ok: false, - error: "tabId and url are required", - }); - return; - } - - try { - var before = await api.tabs.get(tabId); - var wasDiscarded = Boolean(before && before.discarded); - await api.tabs.update(tabId, { url: url, active: false }); - var finalUrl = await waitForTabUrl(tabId, 30000); - if (!finalUrl) { - var after = await api.tabs.get(tabId); - finalUrl = after && after.url ? after.url : url; - } - respond(message.requestId, { - type: "navigate-result", - ok: true, - finalUrl: finalUrl, - wasDiscarded: wasDiscarded, - }); - } catch (error) { - respond(message.requestId, { - type: "navigate-result", - ok: false, - error: error instanceof Error ? error.message : String(error), - }); - } -} - -async function answerProbe(message) { +async function answerProbe(message, reply) { var state = await readHumanState(); var liveUrl = null; if (message.tabId != null && (state.popupEnabled || state.panelEnabled)) { var tabId = typeof message.tabId === "number" ? message.tabId : Number(message.tabId); if (!Number.isInteger(tabId)) { - send({ + reply(message.requestId, { type: "capability-probe-result", - requestId: message.requestId, ok: false, error: "Could not read the tab", popupEnabled: state.popupEnabled, @@ -233,9 +195,8 @@ async function answerProbe(message) { var tab = await api.tabs.get(tabId); liveUrl = tab && typeof tab.url === "string" ? tab.url : null; } catch (error) { - send({ + reply(message.requestId, { type: "capability-probe-result", - requestId: message.requestId, ok: false, error: "Could not read the tab", popupEnabled: state.popupEnabled, @@ -246,9 +207,8 @@ async function answerProbe(message) { } } - send({ + reply(message.requestId, { type: "capability-probe-result", - requestId: message.requestId, ok: true, liveUrl: liveUrl, popupEnabled: state.popupEnabled,