mcp-browser-extension 0.9.29 → 0.9.31

package/README.md

@@ -174,13 +174,24 @@ the way to install it.
 **3. Verify your email.** In your MCP client, ask the agent to call
 `chrome_status`. On this first browser tool call, the client shows an email
 prompt. Enter an address you can access, then open the sign-in link sent to
-that address. The waiting tool reports **Email verified** and continues.
+that address and click **Verify this device**. The waiting tool reports
+**Email verified** and continues.
 
 If the tool returns `ACCESS_PENDING`, ask the agent to call `chrome_status`
 again to keep waiting on the same link. You do not need another email or a
-verification code. The MCP client must support interactive input prompts
-(MCP elicitation). If no prompt appears, enable interactive prompts in your
-client and retry; installing the extension alone does not activate access.
+verification code.
+
+If your client suppresses the prompt (for example, in YOLO/bypass mode), does
+not support MCP elicitation, or the dialog is dismissed, the server automatically
+opens a temporary local verification form in your browser. The tool also returns
+`ACCESS_INPUT_REQUIRED` with the link, so you can open it yourself if necessary
+on the computer running the MCP server. Enter your email in the browser form,
+and open the sign-in link from your inbox. Click **Verify this device**, then
+call `chrome_status` to continue.
+The local form expires after 10 minutes; call the tool again for a fresh one.
+Opening the form does not send an email, and access remains blocked until the
+email link and device grant are verified. Installing the extension alone does
+not activate access.
 
 **4. Click Connect if Chrome is not already paired.** A fresh install opens the
 extension's Settings with a
@@ -675,6 +686,10 @@ what the flags say.
 it says nothing about what is on them. A logged-in page routinely renders a
 session token into a script tag or an API key onto a settings screen.
 
+- **Cookie values are hidden by default.** `get_cookies` returns each cookie's
+  name, domain, path and flags with the value replaced by `[hidden]`. A session
+  cookie can grant access to an account without its password.
+  Pass `--enable-cookie-values` if a task really needs them.
 - **Password field values are always suppressed** — in `get_html`, and in
   `snapshot`, where the field still appears (so you can type into it) flagged
   `secret: true` with no value. No flag, no opt-in: nobody wants those characters.

package/SETUP.md

@@ -128,13 +128,24 @@ the Web Store build passes review separately and can trail it by a version.
 
 The first browser tool call opens an email prompt in the MCP client. Ask the
 human to enter an email address. The website sends a Firebase sign-in link;
-the human opens it in their browser and returns to the MCP client. Do not ask
+the human opens it in their browser, clicks **Verify this device**, and returns
+to the MCP client. Do not ask
 them to copy or paste a verification code. The server detects the verified
 link automatically and reports the result to the waiting tool call. On success,
 the result includes **Email verified** and the requested browser action continues.
 The user does not need to send another chat message. Progress updates and status
 notifications are also sent to clients that display them.
 
+If the client suppresses or cannot display the prompt, or it is dismissed,
+the server automatically opens a temporary local browser form and returns
+`ACCESS_INPUT_REQUIRED` with its link. Show the link as a backup if the form
+did not appear on the computer running the server.
+The human enters their email, opens the sign-in link from their inbox, and clicks
+**Verify this device**. Do not fill
+the form or open their email for them. The form expires after 10 minutes.
+After they submit it, call `chrome_status` to wait for verification.
+YOLO/bypass permission mode does not skip email verification.
+
 If the human explicitly configured `--no-email-verification`, there is no email
 step; continue to pairing. This option is intended only for trusted local
 clients and cannot be combined with a public tunnel.
@@ -146,9 +157,7 @@ remain blocked until access is confirmed. Cancellation stops the waiting action,
 while background verification can still activate the local installation.
 
 Click **Connect** in the extension if the result says Chrome is not already
-paired. This requires the MCP client to
-support elicitation; clients that cannot show the prompt cannot activate
-through this flow.
+paired.
 
 The server also writes a `pairing.json` file for Load unpacked installs, which
 may connect automatically. For the Chrome Web Store copy, or whenever Chrome

package/dist/shared/page-fns.d.ts

@@ -16,12 +16,18 @@
  * One resolver, used by every op, is what closes it.
  */
 /** Ops the page-side dispatcher understands. */
-export type PageOpName = 'probe' | 'text' | 'html' | 'click' | 'type' | 'focus' | 'point' | 'hover' | 'select' | 'measure' | 'scroll' | 'storage' | 'waitSelector' | 'waitFor';
+export type PageOpName = 'probe' | 'text' | 'html' | 'click' | 'check' | 'type' | 'focus' | 'point' | 'hover' | 'select' | 'measure' | 'scroll' | 'storage' | 'waitSelector' | 'waitFor';
 export interface PageOpArgs {
     op: PageOpName;
     selector?: string | null;
     text?: string;
     clear?: boolean;
+    /** type: send keydown/keypress/keyup around each character. */
+    keyEvents?: boolean;
+    /** type: press Enter after the text (submits the field's form like a person would). */
+    pressEnter?: boolean;
+    /** check: the state a checkbox/radio should end up in. */
+    checked?: boolean;
     outer?: boolean;
     values?: string[];
     x?: number | null;

package/dist/shared/page-fns.js

@@ -208,6 +208,18 @@ function pageOp(a) {
                 el.click();
                 return { found: true };
             }
+            case 'check': {
+                if (!el)
+                    return { found: false };
+                // Click only when the state differs: a click toggles, so clicking an
+                // already-checked box to "check" it would clear it.
+                const box = el;
+                if (box.checked !== (a.checked !== false)) {
+                    el.scrollIntoView({ block: 'center' });
+                    el.click();
+                }
+                return { found: true, checked: box.checked };
+            }
             case 'type': {
                 if (!el)
                     return { found: false };
@@ -226,9 +238,32 @@ function pageOp(a) {
                 if (!node)
                     return { found: false };
                 node.focus();
-                const next = (a.clear ? '' : node.value ?? '') + (a.text ?? '');
-                setValue(node, next);
+                if (a.keyEvents) {
+                    // One character at a time, each inside its own key events, for pages
+                    // that react to keystrokes rather than to the value.
+                    if (a.clear)
+                        setValue(node, '');
+                    for (const ch of a.text ?? '') {
+                        const ev = { key: ch, bubbles: true, cancelable: true };
+                        const go = node.dispatchEvent(new KeyboardEvent('keydown', ev));
+                        if (go && node.dispatchEvent(new KeyboardEvent('keypress', ev)))
+                            setValue(node, (node.value ?? '') + ch);
+                        node.dispatchEvent(new KeyboardEvent('keyup', ev));
+                    }
+                }
+                else {
+                    setValue(node, (a.clear ? '' : node.value ?? '') + (a.text ?? ''));
+                }
                 node.dispatchEvent(new Event('change', { bubbles: true }));
+                if (a.pressEnter) {
+                    const ev = { key: 'Enter', code: 'Enter', keyCode: 13, which: 13, bubbles: true, cancelable: true };
+                    const go = node.dispatchEvent(new KeyboardEvent('keydown', ev)) && node.dispatchEvent(new KeyboardEvent('keypress', ev));
+                    node.dispatchEvent(new KeyboardEvent('keyup', ev));
+                    // Synthetic key events never trigger implicit submission; do what the
+                    // browser would for Enter in a single-line field of a form.
+                    if (go && node instanceof HTMLInputElement && node.form)
+                        node.form.requestSubmit();
+                }
                 return { found: true };
             }
             case 'focus': {

package/dist/shared/policy.js

@@ -34,6 +34,12 @@ const READ_CONTENT = new Set([
     'frames_list',
     'observers',
     'print_pdf',
+    // The page's accessibility tree, its cookies (session secrets), and its
+    // web storage are content too. A storage write is refused in safe mode by
+    // the extension's storage handler; the domain gate here covers every op.
+    'snapshot',
+    'get_cookies',
+    'storage',
 ]);
 /** Content-mutating actions — URL-gated AND mutation-gated. */
 const MUTATE_CONTENT = new Set([
@@ -44,6 +50,7 @@ const MUTATE_CONTENT = new Set([
     'hover',
     'scroll',
     'fill_form',
+    'select_option',
 ]);
 /** Navigation — URL-gated by the DESTINATION url, and mutation-gated. */
 const NAVIGATION = new Set([
@@ -72,7 +79,9 @@ function isUrlGated(method) {
         MUTATE_CONTENT.has(method) ||
         NAVIGATION.has(method) ||
         method === 'eval' ||
-        method === 'upload_file');
+        method === 'upload_file' ||
+        // Gated on where the bytes come from: the URL when one is given, else the tab.
+        method === 'download_file');
 }
 // ---------------------------------------------------------------------------
 // Domain matching

package/dist/shared/screenshot.d.ts

@@ -14,8 +14,10 @@ export interface PageDims {
     /** Full content box (document) width/height. */
     fullW: number;
     fullH: number;
-    /** window.devicePixelRatio (default 1). Output pixels = CSS px * dpr * clip.scale. */
+    /** window.devicePixelRatio, including page zoom (default 1). */
     dpr?: number;
+    /** Chrome tab zoom: CSS pixels to device-independent pixels (default 1). */
+    zoom?: number;
     /** Current scroll offset of the top document (default 0,0); a viewport clip starts here. */
     scrollX?: number;
     scrollY?: number;
@@ -35,7 +37,7 @@ export interface ElementRect {
     w: number;
     h: number;
 }
-/** A CDP `Page.captureScreenshot` clip (CSS px; `scale` multiplies output). */
+/** A CDP `Page.captureScreenshot` clip (device-independent px, not CSS px). */
 export interface CaptureClip {
     x: number;
     y: number;

package/dist/shared/screenshot.js

@@ -27,15 +27,20 @@ exports.MAX_CAPTURE_PX = 16384;
  * viewport capture. Heights are clamped to MAX_CAPTURE_PX with `truncated` set.
  */
 function planScreenshot(dims, opts = {}) {
-    // CDP's clip.scale multiplies on top of the device scale factor, so dividing
-    // by the DPR yields exactly `opts.scale` output pixels per CSS pixel.
+    // Page.Viewport uses device-independent pixels, so convert the CSS geometry
+    // by the tab zoom. DPR already includes that zoom: dividing the output scale
+    // by DPR then yields exactly `opts.scale` output pixels per CSS pixel.
     const dpr = dims.dpr && dims.dpr > 0 ? dims.dpr : 1;
+    const zoom = dims.zoom && dims.zoom > 0 ? dims.zoom : 1;
     const scale = (opts.scale && opts.scale > 0 ? opts.scale : exports.DEFAULT_SCREENSHOT_SCALE) / dpr;
+    const clip = (x, y, width, height) => ({
+        x: x * zoom, y: y * zoom, width: width * zoom, height: height * zoom, scale,
+    });
     if (opts.element) {
         const realH = Math.max(1, Math.round(opts.element.h));
         const clipH = Math.min(opts.element.h, exports.MAX_CAPTURE_PX);
         return {
-            clip: { x: opts.element.x, y: opts.element.y, width: opts.element.w, height: clipH, scale },
+            clip: clip(opts.element.x, opts.element.y, opts.element.w, clipH),
             captureBeyondViewport: true,
             width: Math.max(1, Math.round(opts.element.w)),
             height: Math.min(realH, exports.MAX_CAPTURE_PX),
@@ -46,7 +51,7 @@ function planScreenshot(dims, opts = {}) {
     if (opts.fullPage) {
         const clipH = Math.min(dims.fullH, exports.MAX_CAPTURE_PX);
         return {
-            clip: { x: 0, y: 0, width: dims.fullW, height: clipH, scale },
+            clip: clip(0, 0, dims.fullW, clipH),
             captureBeyondViewport: true,
             width: dims.fullW,
             height: clipH,
@@ -54,11 +59,11 @@ function planScreenshot(dims, opts = {}) {
             fullHeight: dims.fullH,
         };
     }
-    // Plain viewport: capture what's visible. A clip is only needed to apply a
-    // scale; at scale 1 on a 1x display the bare capture is identical and cheaper.
+    // Plain viewport: a clip is needed to apply an output scale or page zoom.
+    // The caller can also force a fresh paint with a viewport clip at 100%.
     return {
-        ...(scale !== 1
-            ? { clip: { x: dims.scrollX ?? 0, y: dims.scrollY ?? 0, width: dims.w, height: dims.h, scale } }
+        ...(scale !== 1 || zoom !== 1
+            ? { clip: clip(dims.scrollX ?? 0, dims.scrollY ?? 0, dims.w, dims.h) }
             : {}),
         captureBeyondViewport: false,
         width: dims.w,

package/dist/shared/snapshot.js

@@ -72,6 +72,13 @@ function collectSnapshot(interactiveOnly = true, max = 200, locator = null) {
             if (t)
                 return t;
         }
+        // <label for> or a wrapping <label>: how ordinary forms name their fields.
+        const labels = el.labels;
+        if (labels && labels.length > 0) {
+            const t = Array.from(labels).map((l) => l.innerText).join(' ').replace(/\s+/g, ' ').trim();
+            if (t)
+                return t;
+        }
         const ph = el.getAttribute('placeholder');
         if (ph)
             return ph.trim();
@@ -113,8 +120,11 @@ function collectSnapshot(interactiveOnly = true, max = 200, locator = null) {
     // recursively. Defensive against null/closed shadow roots and re-visits.
     const seen = new Set();
     const candidates = [];
+    // Gather past `max` so hidden candidates dropped below still leave enough to
+    // fill it, and so a page with more than `max` can be reported as truncated.
+    const cap = Math.max(max * 2, max + 50);
     const collect = (root) => {
-        if (candidates.length >= max)
+        if (candidates.length >= cap)
             return;
         let matched;
         try {
@@ -124,7 +134,7 @@ function collectSnapshot(interactiveOnly = true, max = 200, locator = null) {
             matched = [];
         }
         for (let i = 0; i < matched.length; i++) {
-            if (candidates.length >= max)
+            if (candidates.length >= cap)
                 break;
             const el = matched[i];
             if (seen.has(el))
@@ -142,7 +152,7 @@ function collectSnapshot(interactiveOnly = true, max = 200, locator = null) {
             hosts = [];
         }
         for (let i = 0; i < hosts.length; i++) {
-            if (candidates.length >= max)
+            if (candidates.length >= cap)
                 break;
             const sr = hosts[i].shadowRoot;
             if (sr)
@@ -230,7 +240,8 @@ function collectSnapshot(interactiveOnly = true, max = 200, locator = null) {
                 break;
             picked.push(read(el));
         }
-        truncated = els.length > picked.length;
+        // At the cap there may be more on the page than were even looked at.
+        truncated = els.length > picked.length || candidates.length >= cap;
     }
     // -- phase 2: writes (one attribute per returned node) ----------------------
     const nodes = [];

package/dist/src/access-browser.d.ts

@@ -0,0 +1,15 @@
+export interface BrowserEmailPrompt {
+    url: string;
+    close(): void;
+}
+export interface EmailSubmission {
+    ok: boolean;
+    message: string;
+}
+/** Best effort: the tool also returns the link for remote/headless computers. */
+export declare function openBrowserEmailPrompt(url: string): void;
+/** Only the person submitting this form can start an email. GET never sends one. */
+export declare function createBrowserEmailPrompt(submit: (email: string) => Promise<EmailSubmission>, options?: {
+    onClose?: () => void;
+    ttlMs?: number;
+}): Promise<BrowserEmailPrompt>;

package/dist/src/access-browser.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openBrowserEmailPrompt = openBrowserEmailPrompt;
+exports.createBrowserEmailPrompt = createBrowserEmailPrompt;
+/** A temporary loopback email form for clients that cannot display elicitation. */
+const node_crypto_1 = require("node:crypto");
+const node_http_1 = require("node:http");
+const node_child_process_1 = require("node:child_process");
+/** Best effort: the tool also returns the link for remote/headless computers. */
+function openBrowserEmailPrompt(url) {
+    // Only launch a form we host, never a URL received from an MCP request.
+    if (!/^http:\/\/127\.0\.0\.1:\d+\/verify\/[a-f0-9]{64}$/.test(url))
+        return;
+    const command = process.platform === 'darwin' ? 'open'
+        : process.platform === 'win32' ? 'rundll32.exe' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url];
+    try {
+        const child = (0, node_child_process_1.spawn)(command, args, { detached: true, stdio: 'ignore', windowsHide: true });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch { /* Keep the form available even if the operating system cannot open it. */ }
+}
+const escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+function page(path, csrf, message, sent) {
+    return `<!doctype html><html lang="en"><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Verify your email | MCP Browser Extension</title>
+<style>
+  :root{color-scheme:light dark;font-family:system-ui,sans-serif}
+  body{max-width:440px;margin:12vh auto;padding:24px;line-height:1.5}
+  h1{font-size:28px;line-height:1.2} label{display:block;font-weight:600}
+  input,button{box-sizing:border-box;width:100%;font:inherit;padding:12px;margin-top:8px;border:1px solid #888;border-radius:6px}
+  button{margin-top:18px;background:#175cd3;color:white;border-color:#175cd3;cursor:pointer}
+  p{margin:20px 0} .brand{font-size:14px} small{display:block;margin-top:18px}
+</style>
+<body><p class="brand">MCP Browser Extension</p><h1>${sent ? 'Check your inbox' : 'Verify your email'}</h1>
+<p role="status">${escapeHtml(message)}</p>
+${sent ? '<p>After opening the sign-in link, return to your assistant to continue.</p>' : `
+<form method="post" action="${path}">
+  <input type="hidden" name="csrf" value="${csrf}">
+  <label for="email">Email address</label>
+  <input id="email" name="email" type="email" autocomplete="email" maxlength="254" required autofocus>
+  <button type="submit">Send verification link</button>
+</form><small>Your email is sent to mcp-browser-extension.com to verify and manage access.</small>`}
+</body></html>`;
+}
+/** Only the person submitting this form can start an email. GET never sends one. */
+async function createBrowserEmailPrompt(submit, options = {}) {
+    const path = `/verify/${(0, node_crypto_1.randomBytes)(32).toString('hex')}`;
+    const csrf = (0, node_crypto_1.randomBytes)(32).toString('hex');
+    let origin = '';
+    let sent = false;
+    let busy = false;
+    let closed = false;
+    let expiry;
+    const sentMessage = 'A sign-in link has been sent. Open it from your email and click Verify this device to finish verification.';
+    const respond = (res, status, message) => {
+        res.writeHead(status, {
+            'content-type': 'text/html; charset=utf-8',
+            'cache-control': 'no-store',
+            // Keep Origin on same-origin form POSTs; no-referrer makes Chromium send
+            // Origin: null. Cross-origin destinations still receive no referrer.
+            'referrer-policy': 'same-origin',
+            'x-content-type-options': 'nosniff',
+            'x-frame-options': 'DENY',
+            'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; base-uri 'none'; frame-ancestors 'none'",
+        });
+        res.end(page(path, csrf, message, sent));
+    };
+    const server = (0, node_http_1.createServer)((req, res) => {
+        void (async () => {
+            // Exact Host + Origin checks also prevent DNS rebinding and cross-site
+            // submissions. The random path is independent of every device credential.
+            if (req.headers.host !== origin.slice('http://'.length) || req.url !== path) {
+                res.writeHead(404).end();
+                return;
+            }
+            if (req.method === 'GET') {
+                respond(res, 200, sent ? sentMessage : 'Enter your email below. We will send you a one-time sign-in link.');
+                return;
+            }
+            if (req.method !== 'POST') {
+                res.writeHead(405, { allow: 'GET, POST' }).end();
+                return;
+            }
+            if (req.headers.origin !== origin) {
+                res.writeHead(403).end();
+                return;
+            }
+            if (req.headers['content-type']?.split(';')[0] !== 'application/x-www-form-urlencoded') {
+                res.writeHead(415).end();
+                return;
+            }
+            let body = '';
+            let bytes = 0;
+            for await (const chunk of req) {
+                bytes += Buffer.byteLength(chunk);
+                if (bytes > 2048) {
+                    res.writeHead(413).end();
+                    return;
+                }
+                body += chunk.toString();
+            }
+            const fields = new URLSearchParams(body);
+            if (fields.get('csrf') !== csrf) {
+                res.writeHead(403).end();
+                return;
+            }
+            if (sent) {
+                respond(res, 200, sentMessage);
+                return;
+            }
+            if (busy) {
+                respond(res, 409, 'Your request is already being sent. Please wait.');
+                return;
+            }
+            busy = true;
+            try {
+                const outcome = await submit(fields.get('email') ?? '');
+                sent = outcome.ok;
+                respond(res, outcome.ok ? 200 : 400, outcome.ok ? sentMessage : outcome.message);
+            }
+            finally {
+                busy = false;
+            }
+        })().catch(() => { if (!res.headersSent)
+            respond(res, 503, 'The verification service could not be reached. Please try again.'); });
+    });
+    server.requestTimeout = 10_000;
+    server.headersTimeout = 10_000;
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        clearTimeout(expiry);
+        server.close();
+        server.closeAllConnections();
+        options.onClose?.();
+    };
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            server.removeListener('error', reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        close();
+        throw new Error('No loopback address');
+    }
+    origin = `http://127.0.0.1:${address.port}`;
+    expiry = setTimeout(close, options.ttlMs ?? 10 * 60_000);
+    expiry.unref();
+    server.unref();
+    return { url: origin + path, close };
+}
+//# sourceMappingURL=access-browser.js.map

package/dist/src/access.d.ts

@@ -9,6 +9,8 @@ export type AccessRequest = {
 };
 /** @internal Test seam for the verification watcher. */
 export declare function setAccessPollIntervalForTesting(ms: number, waitMs?: number): void;
+/** Close a pending form when verification finishes or its owner shuts down. */
+export declare function closeAccessBrowserPrompt(dataDir: string): void;
 declare function result(message: string): {
     content: {
         type: "text";