@mehmoodqureshi/chrome-mcp 0.9.1 → 0.9.2

package/README.md

@@ -333,6 +333,46 @@ type  { "role": "textbox", "name": "Email", "text": "a@b.com" }
 Resolution is server-side and refuses to guess: an ambiguous locator fails with
 the candidates listed rather than acting on the first one (pass `nth` to pick).
 
+### Did the session expire? — `auth_check` and `failOnAuthWall`
+
+Reusing a signed-in Chrome removes the login step, but a session cookie can
+still expire mid-run. Without a distinct signal the next step fails as
+`SELECTOR_NOT_FOUND` or `TIMEOUT`, and an eval harness scores the run as an
+agent failure when it was an auth failure. Every `snapshot` now carries an
+`authWall` verdict when the page looks like a sign-in wall, and there is a
+dedicated probe:
+
+```jsonc
+auth_check {}                                   // { authRequired, confidence, signals }
+auth_check { "failOnAuthWall": true }           // [AUTH_REQUIRED] error instead
+navigate  { "url": "https://app.example.com/dashboard", "failOnAuthWall": true }
+snapshot  { "failOnAuthWall": true }
+```
+
+For a harness, set it once instead of per call:
+
+```
+npx -y @mehmoodqureshi/chrome-mcp --allow-domain app.example.com --enable-mutations --fail-on-auth-wall
+```
+
+With the flag on, every step that can move the tab (`navigate`, `click`, `type`,
+`select_option`, `press`, `fill_form`, `back`, `forward`, `reload`) checks the
+page it landed on and fails with `[AUTH_REQUIRED]` if that page is a sign-in
+wall, and a `wait_for` that times out on such a page reports `[AUTH_REQUIRED]`
+instead of `[TIMEOUT]`. Each guarded step costs one extra snapshot round-trip;
+with the flag off the cost is zero. `[AUTH_REQUIRED]` is where a harness pauses
+for a human to sign in again in the same Chrome, then retries the step. chrome-mcp
+never re-authenticates on its own: it holds no credentials, by design.
+
+Detection reads only what the snapshot already has: the URL (sign-in routes,
+identity-provider hosts such as `accounts.google.com`, `login.microsoftonline.com`,
+Okta, Auth0), the title, password fields, and sign-in controls. `high`
+confidence needs two independent cues (a password field plus a sign-in button,
+say); a lone password field or a bare `/auth/...` URL is `medium`. A header
+"Sign in" link on an ordinary page never counts. `failOnAuthWall` fires only on
+`high`, so a harness can bucket `[AUTH_REQUIRED]` separately from every other
+failure while a settings page with a "current password" field carries on.
+
 ### Printing — `print_pdf`
 
 ```jsonc

package/dist/shared/auth-wall.d.ts

@@ -0,0 +1,51 @@
+/**
+ * shared/auth-wall.ts — decide whether a page is a login wall.
+ *
+ * A browser agent that reuses a signed-in Chrome profile still hits the moment
+ * the session cookie expires mid-run: the next page is a sign-in form, and
+ * every later step fails for a reason that has nothing to do with the task.
+ * Without a distinct signal, an eval harness buckets that as SELECTOR_NOT_FOUND
+ * or TIMEOUT and the run is scored as an agent failure instead of an auth
+ * failure.
+ *
+ * This module is the pure decision. It reads only what an accessibility
+ * snapshot already carries (URL, title, password fields, button/link names), so
+ * it works identically on both backends and needs nothing new from the
+ * extension. Server-side callers attach the verdict to snapshot results, expose
+ * it as `auth_check`, and can turn it into an `AUTH_REQUIRED` error.
+ */
+export type AuthWallConfidence = 'high' | 'medium';
+export type AuthWallSignal = 'password-field' | 'login-url' | 'identity-provider' | 'login-title' | 'login-button' | 'username-field';
+export interface AuthWall {
+    detected: true;
+    confidence: AuthWallConfidence;
+    signals: AuthWallSignal[];
+}
+/** The subset of a snapshot the detector reads. */
+export interface AuthWallPage {
+    url: string;
+    title: string;
+    nodes: Array<{
+        role: string;
+        name: string;
+        tag: string;
+        secret?: boolean;
+    }>;
+}
+/**
+ * Inspect a page and return a verdict, or `null` when it does not look like a
+ * login wall.
+ *
+ * Confidence:
+ * - `high`: a password field plus a sign-in control, title, or URL; or a
+ *   sign-in URL plus a sign-in control or title; or an identity-provider host.
+ * - `medium`: exactly one weaker cue on its own (a password field, or a
+ *   sign-in URL) with nothing to corroborate it. Callers that fail a run on a
+ *   wall should usually require `high`.
+ *
+ * A lone "Sign in" link or a title mention never counts: most public pages have
+ * one in the header.
+ */
+export declare function detectAuthWall(page: AuthWallPage): AuthWall | null;
+/** A one-line, human-readable explanation for error messages and logs. */
+export declare function describeAuthWall(wall: AuthWall, url: string): string;

package/dist/shared/auth-wall.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * shared/auth-wall.ts — decide whether a page is a login wall.
+ *
+ * A browser agent that reuses a signed-in Chrome profile still hits the moment
+ * the session cookie expires mid-run: the next page is a sign-in form, and
+ * every later step fails for a reason that has nothing to do with the task.
+ * Without a distinct signal, an eval harness buckets that as SELECTOR_NOT_FOUND
+ * or TIMEOUT and the run is scored as an agent failure instead of an auth
+ * failure.
+ *
+ * This module is the pure decision. It reads only what an accessibility
+ * snapshot already carries (URL, title, password fields, button/link names), so
+ * it works identically on both backends and needs nothing new from the
+ * extension. Server-side callers attach the verdict to snapshot results, expose
+ * it as `auth_check`, and can turn it into an `AUTH_REQUIRED` error.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectAuthWall = detectAuthWall;
+exports.describeAuthWall = describeAuthWall;
+/** Path segments that mark a sign-in route on most stacks. */
+const LOGIN_PATH = /(^|[\/._-])(login|log-in|logon|log-on|signin|sign-in|sign_in|authenticate|auth|sso|oauth2?|saml|sessions?\/new|users\/sign_in|account\/login|idp)([\/?#._-]|$)/i;
+/** Hosts (or host suffixes) that are identity providers, whatever the path. */
+const IDP_HOSTS = [
+    'accounts.google.com',
+    'login.microsoftonline.com',
+    'login.live.com',
+    'login.microsoft.com',
+    'appleid.apple.com',
+    'login.yahoo.com',
+    'auth0.com',
+    'okta.com',
+    'oktapreview.com',
+    'onelogin.com',
+    'pingidentity.com',
+    'duosecurity.com',
+    'github.com/login',
+    'login.salesforce.com',
+    'signin.aws.amazon.com',
+    'auth.atlassian.com',
+    'id.atlassian.com',
+    'login.linkedin.com',
+];
+const LOGIN_TITLE = /\b(sign in|sign-in|signin|log in|log-in|login|log on|logon|authenticate|authentication required|session (has )?expired|session timed out|please sign in|please log in|verify it'?s you)\b/i;
+/** Button/link labels that submit or start a sign-in. Anchored so a header "Sign in" link with extra copy still matches only when the label is the action. */
+const LOGIN_BUTTON = /^(sign in|sign-in|signin|log in|log-in|login|log on|logon|continue|next|submit|authenticate|(sign|log) ?in (with|via|using) .{1,40}|continue with .{1,40}|use (your )?password|sign in to continue|log in to continue)$/i;
+/** Labels that mark a credential's username half; only a booster, never a wall on its own. */
+const USERNAME_FIELD = /\b(email|e-mail|username|user name|user id|userid|phone|account|login id)\b/i;
+/** The action-shaped labels that, next to a password field, make this a form and not a "change password" settings page. */
+const STRONG_BUTTON = /^(sign in|sign-in|signin|log in|log-in|login|log on|logon|authenticate|sign in to continue|log in to continue|(sign|log) ?in (with|via|using) .{1,40}|continue with .{1,40})$/i;
+function parseUrl(url) {
+    try {
+        return new URL(url);
+    }
+    catch {
+        return null;
+    }
+}
+function isIdpHost(u) {
+    const host = u.hostname.toLowerCase();
+    const hostAndPath = `${host}${u.pathname}`.toLowerCase();
+    return IDP_HOSTS.some((h) => {
+        if (h.includes('/'))
+            return hostAndPath === h || hostAndPath.startsWith(`${h}/`);
+        return host === h || host.endsWith(`.${h}`);
+    });
+}
+/**
+ * Inspect a page and return a verdict, or `null` when it does not look like a
+ * login wall.
+ *
+ * Confidence:
+ * - `high`: a password field plus a sign-in control, title, or URL; or a
+ *   sign-in URL plus a sign-in control or title; or an identity-provider host.
+ * - `medium`: exactly one weaker cue on its own (a password field, or a
+ *   sign-in URL) with nothing to corroborate it. Callers that fail a run on a
+ *   wall should usually require `high`.
+ *
+ * A lone "Sign in" link or a title mention never counts: most public pages have
+ * one in the header.
+ */
+function detectAuthWall(page) {
+    const signals = new Set();
+    const u = parseUrl(page.url);
+    if (u && LOGIN_PATH.test(u.pathname))
+        signals.add('login-url');
+    if (u && isIdpHost(u))
+        signals.add('identity-provider');
+    if (LOGIN_TITLE.test(page.title || ''))
+        signals.add('login-title');
+    let strongButton = false;
+    for (const n of page.nodes) {
+        if (n.secret === true || (n.tag === 'input' && n.role === 'textbox' && /password/i.test(n.name))) {
+            signals.add('password-field');
+            continue;
+        }
+        const label = (n.name || '').trim();
+        if (!label)
+            continue;
+        const clickable = n.role === 'button' || n.role === 'link' || n.tag === 'button';
+        if (clickable && LOGIN_BUTTON.test(label)) {
+            signals.add('login-button');
+            if (STRONG_BUTTON.test(label))
+                strongButton = true;
+        }
+        else if ((n.role === 'textbox' || n.role === 'combobox') && USERNAME_FIELD.test(label)) {
+            signals.add('username-field');
+        }
+    }
+    const has = (s) => signals.has(s);
+    const password = has('password-field');
+    const loginUrl = has('login-url');
+    const idp = has('identity-provider');
+    const title = has('login-title');
+    let confidence = null;
+    if (idp)
+        confidence = 'high';
+    else if (password && (strongButton || title || loginUrl || has('username-field')))
+        confidence = 'high';
+    else if (loginUrl && (strongButton || title || has('username-field')))
+        confidence = 'high';
+    else if (password || loginUrl)
+        confidence = 'medium';
+    if (!confidence)
+        return null;
+    const order = [
+        'password-field',
+        'identity-provider',
+        'login-url',
+        'login-title',
+        'login-button',
+        'username-field',
+    ];
+    return { detected: true, confidence, signals: order.filter(has) };
+}
+/** A one-line, human-readable explanation for error messages and logs. */
+function describeAuthWall(wall, url) {
+    return `the page at ${url} looks like a sign-in wall (${wall.confidence} confidence: ${wall.signals.join(', ')}); the session has probably expired`;
+}
+//# sourceMappingURL=auth-wall.js.map

package/dist/src/config.js

@@ -150,6 +150,9 @@ function parseArgs(argv) {
                 policyFlags.redact = true;
                 (policyFlags.redactPatterns ??= []).push(requireValue(argv[++i], '--redact-pattern'));
                 break;
+            case '--fail-on-auth-wall':
+                policyFlags.failOnAuthWall = true;
+                break;
             case '--cdp-fallback':
                 cdpFallback = true;
                 break;
@@ -310,6 +313,10 @@ Security (default: deny-all safe mode):
                          tokens, private keys) out of page reads. Password field
                          values are always suppressed, with or without this.
   --redact-pattern <re>  Add a redaction regex (repeatable; implies --redact)
+  --fail-on-auth-wall    Fail any navigate/click/type/press/back/reload/wait_for
+                         with [AUTH_REQUIRED] when the page it lands on is a
+                         high-confidence sign-in wall (expired session), so an
+                         eval harness never scores it as some other failure.
 
 Misc:
   --log-level <lvl>      silent | info | debug (default info)

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

@@ -54,6 +54,15 @@ export interface StubOptions {
     snapshotNodes?: SnapshotNode[];
     /** Frames the stub reports for `frames_list`. */
     frames?: FrameInfo[];
+    /** Applied after any action or history move: models a click/submit/back that
+     *  lands the tab on a different page (e.g. a redirect to a sign-in wall). */
+    afterAction?: {
+        url?: string;
+        nodes?: SnapshotNode[];
+    };
+    /** When true, `waitFor` rejects with TIMEOUT - the error a wait on a page
+     *  that silently became a login form used to surface. */
+    waitForTimesOut?: boolean;
     /** What the in-page observers return. Absent = the hook is not installed,
      *  which is the case the tools must report clearly rather than as an empty list. */
     observers?: ObserverReadResult;
@@ -76,6 +85,10 @@ export declare class StubExecutor implements Executor {
     snapshotNodes: SnapshotNode[];
     private readonly frames;
     private readonly observerState?;
+    private readonly afterAction?;
+    private readonly waitForTimesOut;
+    /** How many snapshots were taken - the auth guard must cost none when off. */
+    snapshotCalls: number;
     /** The last observer args received, so a test can assert what was requested. */
     lastObserverArgs?: ObserverArgs;
     /** How many times the gate actually asked for the tab list — the round-trip
@@ -110,6 +123,8 @@ export declare class StubExecutor implements Executor {
     back(): Promise<NavResult>;
     forward(): Promise<NavResult>;
     reload(): Promise<NavResult>;
+    /** Move the stub tab to the configured post-action page, if any. */
+    private landed;
     click(): Promise<ActionOk>;
     type(): Promise<ActionOk>;
     fill(): Promise<ActionOk>;

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

@@ -32,6 +32,10 @@ class StubExecutor {
     snapshotNodes;
     frames;
     observerState;
+    afterAction;
+    waitForTimesOut;
+    /** How many snapshots were taken - the auth guard must cost none when off. */
+    snapshotCalls = 0;
     /** The last observer args received, so a test can assert what was requested. */
     lastObserverArgs;
     /** How many times the gate actually asked for the tab list — the round-trip
@@ -40,6 +44,8 @@ class StubExecutor {
     ready = false;
     constructor(opts = {}) {
         this.url = opts.activeUrl ?? 'about:blank';
+        this.afterAction = opts.afterAction;
+        this.waitForTimesOut = opts.waitForTimesOut ?? false;
         this.evalThrows = opts.evalThrows ?? false;
         this.tabsListThrows = opts.tabsListThrows ?? false;
         this.noTabs = opts.noTabs ?? false;
@@ -133,15 +139,28 @@ class StubExecutor {
         return { url: args.url, title: 'Stub Page', httpStatus: 200 };
     }
     async back() {
+        this.landed();
         return { url: this.url, title: 'Stub Page' };
     }
     async forward() {
+        this.landed();
         return { url: this.url, title: 'Stub Page' };
     }
     async reload() {
+        this.landed();
         return { url: this.url, title: 'Stub Page' };
     }
+    /** Move the stub tab to the configured post-action page, if any. */
+    landed() {
+        if (!this.afterAction)
+            return;
+        if (this.afterAction.url !== undefined)
+            this.url = this.afterAction.url;
+        if (this.afterAction.nodes !== undefined)
+            this.snapshotNodes = this.afterAction.nodes;
+    }
     async click() {
+        this.landed();
         return ok;
     }
     async type() {
@@ -149,18 +168,22 @@ class StubExecutor {
             this.remainingWriteDisconnects--;
             throw new types_1.ExecutorError('EXTENSION_DISCONNECTED', 'stub: service worker recycled mid-command');
         }
+        this.landed();
         return ok;
     }
     async fill() {
+        this.landed();
         return ok;
     }
     async press() {
+        this.landed();
         return ok;
     }
     async hover() {
         return ok;
     }
     async selectOption() {
+        this.landed();
         return ok;
     }
     async scroll() {
@@ -175,6 +198,7 @@ class StubExecutor {
         return { html: this.htmlPayload };
     }
     async snapshot() {
+        this.snapshotCalls++;
         return { url: this.url, title: 'Stub Page', nodes: this.snapshotNodes, truncated: false };
     }
     async getCookies() {
@@ -195,6 +219,8 @@ class StubExecutor {
         return { ok: true, value: 'stub-value', type: 'string' };
     }
     async waitFor() {
+        if (this.waitForTimesOut)
+            throw new types_1.ExecutorError('TIMEOUT', 'stub: wait_for timed out');
         return { matched: true, waitedMs: 0 };
     }
     async download(args) {

package/dist/src/executor/types.d.ts

@@ -349,7 +349,9 @@ export interface Executor {
  * (which only carries codes that originate inside the extension); these extra
  * codes describe failures on the server half (no backend, launch failed, etc.).
  */
-export type ExecutorErrorCodeLocal = 'NO_BACKEND' | 'EXTENSION_DISCONNECTED' | 'TIMEOUT' | 'TAB_NOT_FOUND' | 'STALE_TAB' | 'SELECTOR_NOT_FOUND' | 'REF_EXPIRED' | 'EVAL_FAILED' | 'LAUNCH_FAILED' | 'DETACHED' | 'TARGET_GONE' | 'POLICY_DENIED' | 'DEVTOOLS_OPEN' | 'DOWNLOAD_FAILED' | 'UPLOAD_FAILED' | 'FRAME_NOT_FOUND' | 'OBSERVERS_DISABLED' | 'UNSUPPORTED' | 'BACKPRESSURE';
+export type ExecutorErrorCodeLocal = 'NO_BACKEND' | 'EXTENSION_DISCONNECTED' | 'TIMEOUT' | 'TAB_NOT_FOUND' | 'STALE_TAB' | 'SELECTOR_NOT_FOUND' | 'REF_EXPIRED' | 'EVAL_FAILED' | 'LAUNCH_FAILED' | 'DETACHED' | 'TARGET_GONE' | 'POLICY_DENIED' | 'DEVTOOLS_OPEN' | 'DOWNLOAD_FAILED' | 'UPLOAD_FAILED' | 'FRAME_NOT_FOUND' | 'OBSERVERS_DISABLED' | 'UNSUPPORTED' | 'BACKPRESSURE'
+/** The page is a sign-in wall (session expired mid-run). Raised only when the caller opts in via `failOnAuthWall`. */
+ | 'AUTH_REQUIRED';
 export declare class ExecutorError extends Error {
     readonly code: ExecutorErrorCodeLocal;
     constructor(code: ExecutorErrorCodeLocal, message: string);

package/dist/src/mcp/tools.js

@@ -29,6 +29,7 @@ const helpers_1 = require("./helpers");
 const redact_1 = require("./redact");
 const locate_1 = require("./locate");
 const snapdiff_1 = require("./snapdiff");
+const auth_wall_1 = require("../../shared/auth-wall");
 const audit_1 = require("./audit");
 const log_1 = require("./log");
 const tasks_1 = require("../bridge/tasks");
@@ -40,6 +41,7 @@ const TARGET_PROPS = {
     ref: zod_1.z.string().describe('Element ref from a prior read (exactly one of selector|ref)').optional(),
 };
 const tabIdField = zod_1.z.string().describe('Target tab id (defaults to the active tab)').optional();
+const authWallField = zod_1.z.boolean().describe('Fail with [AUTH_REQUIRED] when the page this call lands on is a high-confidence sign-in wall (session expired). Off by default unless the server runs with --fail-on-auth-wall; snapshot still reports the verdict as `authWall` either way.').optional();
 /**
  * Frame targeting. Omitted = the top frame, which is what every call did before
  * frames were addressable. `allFrames` is the one to reach for when a selector
@@ -79,27 +81,27 @@ exports.TOOL_DEFINITIONS = [
     { name: 'tab_select', description: 'Make a tab active by tabId.', inputSchema: { tabId: zod_1.z.string() } },
     { name: 'tab_new', description: 'Open a NEW tab (optionally at a URL) and focus it. Prefer this over `navigate` when the user says "open"/"go to" a site — `navigate` REPLACES the current tab. Pass active:false to open in the background (used by parallel batches).', inputSchema: { url: zod_1.z.string().optional(), active: zod_1.z.boolean().optional() } },
     { name: 'tab_close', description: 'Close a tab by tabId.', inputSchema: { tabId: zod_1.z.string() } },
-    { name: 'navigate', description: 'Navigate a tab to a URL, REPLACING its current page. Acts on the active tab unless tabId is given — to open a site without losing the current page, use `tab_new` instead.', inputSchema: { url: zod_1.z.string(), tabId: tabIdField, waitUntil: waitUntilField } },
-    { name: 'back', description: 'Go back in history.', inputSchema: { tabId: tabIdField } },
-    { name: 'forward', description: 'Go forward in history.', inputSchema: { tabId: tabIdField } },
-    { name: 'reload', description: 'Reload the active (or given) tab.', inputSchema: { tabId: tabIdField, waitUntil: waitUntilField } },
-    { name: 'click', description: 'Click an element. Target by selector, a snapshot ref, or role+name (e.g. role:"button", name:"Sign in") - the locator needs no snapshot first. trusted=true uses real OS-level input.', inputSchema: { ...TARGET_PROPS, ...LOCATOR_PROPS, ...FRAME_PROPS, tabId: tabIdField, button: zod_1.z.enum(['left', 'right', 'middle']).optional(), clickCount: zod_1.z.number().optional(), trusted: zod_1.z.boolean().optional(), snapshotAfter: snapshotAfterField } },
-    { name: 'type', description: 'Type text into an element (target by selector, ref, or role+name). trusted=true sends real keystrokes (works on React/Vue controlled inputs).', inputSchema: { ...TARGET_PROPS, ...LOCATOR_PROPS, ...FRAME_PROPS, text: zod_1.z.string(), tabId: tabIdField, clear: zod_1.z.boolean().optional(), pressEnter: zod_1.z.boolean().optional(), keyEvents: zod_1.z.boolean().optional(), trusted: zod_1.z.boolean().optional(), snapshotAfter: snapshotAfterField } },
-    { name: 'select_option', description: 'Select option(s) of a <select> by value or visible label.', inputSchema: { ...TARGET_PROPS, ...LOCATOR_PROPS, ...FRAME_PROPS, values: zod_1.z.array(zod_1.z.string()), tabId: tabIdField, snapshotAfter: snapshotAfterField } },
-    { name: 'press', description: 'Press a key (with optional modifiers).', inputSchema: { key: zod_1.z.string(), modifiers: zod_1.z.array(zod_1.z.string()).optional(), tabId: tabIdField } },
+    { name: 'navigate', description: 'Navigate a tab to a URL, REPLACING its current page. Acts on the active tab unless tabId is given — to open a site without losing the current page, use `tab_new` instead.', inputSchema: { url: zod_1.z.string(), tabId: tabIdField, waitUntil: waitUntilField, failOnAuthWall: authWallField } },
+    { name: 'back', description: 'Go back in history.', inputSchema: { tabId: tabIdField, failOnAuthWall: authWallField } },
+    { name: 'forward', description: 'Go forward in history.', inputSchema: { tabId: tabIdField, failOnAuthWall: authWallField } },
+    { name: 'reload', description: 'Reload the active (or given) tab.', inputSchema: { tabId: tabIdField, waitUntil: waitUntilField, failOnAuthWall: authWallField } },
+    { name: 'click', description: 'Click an element. Target by selector, a snapshot ref, or role+name (e.g. role:"button", name:"Sign in") - the locator needs no snapshot first. trusted=true uses real OS-level input.', inputSchema: { ...TARGET_PROPS, ...LOCATOR_PROPS, ...FRAME_PROPS, tabId: tabIdField, button: zod_1.z.enum(['left', 'right', 'middle']).optional(), clickCount: zod_1.z.number().optional(), trusted: zod_1.z.boolean().optional(), snapshotAfter: snapshotAfterField, failOnAuthWall: authWallField } },
+    { name: 'type', description: 'Type text into an element (target by selector, ref, or role+name). trusted=true sends real keystrokes (works on React/Vue controlled inputs).', inputSchema: { ...TARGET_PROPS, ...LOCATOR_PROPS, ...FRAME_PROPS, text: zod_1.z.string(), tabId: tabIdField, clear: zod_1.z.boolean().optional(), pressEnter: zod_1.z.boolean().optional(), keyEvents: zod_1.z.boolean().optional(), trusted: zod_1.z.boolean().optional(), snapshotAfter: snapshotAfterField, failOnAuthWall: authWallField } },
+    { name: 'select_option', description: 'Select option(s) of a <select> by value or visible label.', inputSchema: { ...TARGET_PROPS, ...LOCATOR_PROPS, ...FRAME_PROPS, values: zod_1.z.array(zod_1.z.string()), tabId: tabIdField, snapshotAfter: snapshotAfterField, failOnAuthWall: authWallField } },
+    { name: 'press', description: 'Press a key (with optional modifiers).', inputSchema: { key: zod_1.z.string(), modifiers: zod_1.z.array(zod_1.z.string()).optional(), tabId: tabIdField, failOnAuthWall: authWallField } },
     { name: 'hover', description: 'Hover over an element.', inputSchema: { ...TARGET_PROPS, ...LOCATOR_PROPS, ...FRAME_PROPS, tabId: tabIdField, snapshotAfter: snapshotAfterField } },
     { name: 'scroll', description: 'Scroll the page or to an element.', inputSchema: { ...TARGET_PROPS, ...FRAME_PROPS, x: zod_1.z.number().optional(), y: zod_1.z.number().optional(), deltaX: zod_1.z.number().optional(), deltaY: zod_1.z.number().optional(), tabId: tabIdField } },
     { name: 'screenshot', description: 'Capture a PNG screenshot (page or element).', inputSchema: { ...TARGET_PROPS, ...FRAME_PROPS, fullPage: zod_1.z.boolean().optional(), tabId: tabIdField } },
     { name: 'get_text', description: 'Get visible text of the page or an element.', inputSchema: { ...TARGET_PROPS, ...FRAME_PROPS, tabId: tabIdField, maxBytes: maxBytesField } },
     { name: 'get_html', description: 'Get HTML of the page or an element. Output is capped (see maxBytes) and cut at a tag boundary; narrow it with `selector` rather than raising the cap when you can. Password field values are always blanked.', inputSchema: { ...TARGET_PROPS, ...FRAME_PROPS, outer: zod_1.z.boolean().optional(), tabId: tabIdField, maxBytes: maxBytesField } },
-    { name: 'snapshot', description: 'Accessibility snapshot: interactive elements with refs to target by `ref` (more reliable than guessing CSS selectors). Pass diff:true to get only what changed since the last snapshot of this tab - far cheaper in a click/read loop. Password fields appear as secret:true with no value.', inputSchema: { interactiveOnly: zod_1.z.boolean().optional(), max: zod_1.z.number().optional(), diff: zod_1.z.boolean().describe('Return added/removed/changed elements since the previous snapshot of this tab instead of the whole tree').optional(), ...FRAME_PROPS, tabId: tabIdField } },
+    { name: 'snapshot', description: 'Accessibility snapshot: interactive elements with refs to target by `ref` (more reliable than guessing CSS selectors). Pass diff:true to get only what changed since the last snapshot of this tab - far cheaper in a click/read loop. Password fields appear as secret:true with no value.', inputSchema: { interactiveOnly: zod_1.z.boolean().optional(), max: zod_1.z.number().optional(), diff: zod_1.z.boolean().describe('Return added/removed/changed elements since the previous snapshot of this tab instead of the whole tree').optional(), failOnAuthWall: authWallField, ...FRAME_PROPS, tabId: tabIdField } },
     { name: 'get_cookies', description: "Read cookies visible to the tab's URL (or a given url).", inputSchema: { url: zod_1.z.string().optional(), tabId: tabIdField } },
     { name: 'storage', description: 'Read/write localStorage (or sessionStorage). op: get|set|remove|clear.', inputSchema: { op: zod_1.z.enum(['get', 'set', 'remove', 'clear']), key: zod_1.z.string().optional(), value: zod_1.z.string().optional(), session: zod_1.z.boolean().optional(), tabId: tabIdField } },
     { name: 'eval', description: 'Evaluate JavaScript in the page (disabled in safe-mode).', inputSchema: { expression: zod_1.z.string(), awaitPromise: zod_1.z.boolean().optional(), ...FRAME_PROPS, tabId: tabIdField } },
-    { name: 'wait_for', description: 'Wait for a selector or text to appear/disappear.', inputSchema: { selector: zod_1.z.string().optional(), textContains: zod_1.z.string().optional(), gone: zod_1.z.boolean().optional(), timeoutMs: zod_1.z.number().optional(), ...FRAME_PROPS, tabId: tabIdField } },
+    { name: 'wait_for', description: 'Wait for a selector or text to appear/disappear.', inputSchema: { selector: zod_1.z.string().optional(), textContains: zod_1.z.string().optional(), gone: zod_1.z.boolean().optional(), timeoutMs: zod_1.z.number().optional(), ...FRAME_PROPS, tabId: tabIdField, failOnAuthWall: authWallField } },
     { name: 'extract_links', description: 'Extract anchors from the page or a subtree. dedupe=true collapses links sharing an href (nav/footer noise); limit caps the count.', inputSchema: { selector: zod_1.z.string().optional(), sameOriginOnly: zod_1.z.boolean().optional(), dedupe: zod_1.z.boolean().optional(), limit: zod_1.z.number().optional(), ...FRAME_PROPS, tabId: tabIdField } },
     { name: 'read_as_markdown', description: 'Read the page (or subtree) as readable markdown.', inputSchema: { selector: zod_1.z.string().optional(), ...FRAME_PROPS, tabId: tabIdField, maxBytes: maxBytesField } },
-    { name: 'fill_form', description: 'Fill multiple fields (keyed by selector) and optionally submit.', inputSchema: { fields: zod_1.z.record(zod_1.z.string(), zod_1.z.union([zod_1.z.string(), zod_1.z.boolean()])), submitSelector: zod_1.z.string().optional(), ...FRAME_PROPS, tabId: tabIdField } },
+    { name: 'fill_form', description: 'Fill multiple fields (keyed by selector) and optionally submit.', inputSchema: { fields: zod_1.z.record(zod_1.z.string(), zod_1.z.union([zod_1.z.string(), zod_1.z.boolean()])), submitSelector: zod_1.z.string().optional(), ...FRAME_PROPS, tabId: tabIdField, failOnAuthWall: authWallField } },
     { name: 'download_file', description: 'Download a file by URL or from a link element.', inputSchema: { url: zod_1.z.string().optional(), ...TARGET_PROPS, suggestedName: zod_1.z.string().optional(), tabId: tabIdField } },
     { name: 'upload_file', description: 'Set local file(s) on a file <input> (target by selector or ref) — uploads without the OS dialog. Requires --enable-uploads. `files` are absolute local paths.', inputSchema: { ...TARGET_PROPS, files: zod_1.z.array(zod_1.z.string()), tabId: tabIdField } },
     {
@@ -161,6 +163,7 @@ exports.TOOL_DEFINITIONS = [
         },
     },
     { name: 'chrome_status', description: 'Report backend/session status.', inputSchema: {} },
+    { name: 'auth_check', description: 'Is the tab sitting on a sign-in wall? Reads the page (URL, title, password fields, sign-in controls) and returns { authRequired, confidence, signals }. Use it after a navigate, or whenever a step fails unexpectedly, to tell "the session expired" apart from "the agent got lost". Pass failOnAuthWall:true to get an [AUTH_REQUIRED] error instead of a verdict, so a harness can bucket the run as an auth failure.', inputSchema: { failOnAuthWall: authWallField, ...FRAME_PROPS, tabId: tabIdField } },
     { name: 'profile_use', description: 'Switch the active browser profile (identity). Subsequent downloads, results, screenshots, and the action log are stored under profiles/<name>/. Resets the active task to "default" unless you then call task_new.', inputSchema: { name: zod_1.z.string().describe('Profile name (becomes a folder; sanitized to a safe path segment).') } },
     { name: 'task_new', description: 'Start a new task (run) under the active profile. Creates profiles/<profile>/tasks/<name>/ with downloads/, results/, screenshots/ and makes it the active task so all captured artifacts land there.', inputSchema: { name: zod_1.z.string().describe('Task name (becomes a folder; sanitized to a safe path segment).') } },
     { name: 'tasks_list', description: 'List every task across all profiles under the data dir, with sizes and download counts.', inputSchema: {} },
@@ -317,6 +320,51 @@ function redaction(policy) {
     return cfg;
 }
 /** The scope a tab's remembered snapshot lives under. */
+/**
+ * Throw `[AUTH_REQUIRED]` when the caller asked for it and the page is a
+ * high-confidence sign-in wall. Medium-confidence verdicts never fail a call: a
+ * lone password field on an otherwise ordinary page is not worth aborting over.
+ */
+function failIfAuthWall(wall, url, a, policy) {
+    if (!wall || wall.confidence !== 'high')
+        return;
+    if (!authGuardOn(a, policy))
+        return;
+    throw new types_1.ExecutorError('AUTH_REQUIRED', (0, auth_wall_1.describeAuthWall)(wall, url));
+}
+/** The guard is on for this call when the caller asked, or the server runs with `--fail-on-auth-wall`. */
+function authGuardOn(a, policy) {
+    return (0, validators_1.optionalBoolean)(a, 'failOnAuthWall') === true || policy.failOnAuthWall === true;
+}
+/**
+ * After an action or history move: when the guard is on, look at the page the
+ * tab landed on and fail with `AUTH_REQUIRED` if it is a sign-in wall. Costs
+ * one snapshot round-trip, and only when the guard is on. The snapshot is
+ * remembered for this tab so a later `snapshot { diff: true }` stays coherent.
+ */
+async function guardAuthWall(ctx, a) {
+    if (!authGuardOn(a, ctx.policy))
+        return;
+    const snap = await ctx.ex.snapshot({ tabId: tabId(a), interactiveOnly: true, max: 200 });
+    (0, snapdiff_1.rememberSnapshot)(snapScope(a), snap);
+    failIfAuthWall((0, auth_wall_1.detectAuthWall)(snap), snap.url, a, ctx.policy);
+}
+/**
+ * A wait that timed out on a page that has become a sign-in wall is an auth
+ * failure, not a slow page. With the guard on, reclassify it.
+ */
+async function reclassifyTimeout(ctx, a, err) {
+    if (err instanceof types_1.ExecutorError && err.code === 'TIMEOUT' && authGuardOn(a, ctx.policy)) {
+        await guardAuthWall(ctx, a);
+    }
+    throw err;
+}
+/** The `authWall` field to spread onto a page-read result: present only when detected. */
+function authWallOf(ctx, snap, a) {
+    const wall = (0, auth_wall_1.detectAuthWall)(snap);
+    failIfAuthWall(wall, snap.url, a, ctx.policy);
+    return wall ? { authWall: wall } : {};
+}
 const snapScope = (a) => (0, snapdiff_1.scopeOf)((0, workspace_1.peekActiveWorkspace)()?.profile ?? 'default', tabId(a));
 /**
  * Render an action's result, optionally with what the action CHANGED on the
@@ -324,13 +372,20 @@ const snapScope = (a) => (0, snapdiff_1.scopeOf)((0, workspace_1.peekActiveWorks
  * re-read, which is the expensive half of every click-then-look loop.
  */
 async function actionResult(ctx, a, payload) {
-    if ((0, validators_1.optionalBoolean)(a, 'snapshotAfter') !== true)
+    const wantDiff = (0, validators_1.optionalBoolean)(a, 'snapshotAfter') === true;
+    const guard = authGuardOn(a, ctx.policy);
+    if (!wantDiff && !guard)
         return (0, envelopes_1.jsonResult)(payload);
     const scope = snapScope(a);
     const previous = (0, snapdiff_1.lastSnapshot)(scope);
     const snap = await ctx.ex.snapshot({ tabId: tabId(a), max: 200, ...frameOpts(a) });
-    const diff = (0, snapdiff_1.diffSnapshots)(previous, snap);
+    // One snapshot serves both: the auth guard reads it first (and aborts the
+    // call if the action landed on a sign-in wall), then the diff is built.
+    failIfAuthWall((0, auth_wall_1.detectAuthWall)(snap), snap.url, a, ctx.policy);
     const stored = (0, snapdiff_1.rememberSnapshot)(scope, snap);
+    if (!wantDiff)
+        return (0, envelopes_1.jsonResult)(payload);
+    const diff = (0, snapdiff_1.diffSnapshots)(previous, snap);
     return (0, envelopes_1.jsonResult)({ ...payload, changed: { ...diff, snapshotId: stored.id, url: snap.url } });
 }
 /**
@@ -403,19 +458,31 @@ exports.TOOL_HANDLERS = {
     navigate: async (a, ctx) => {
         const url = (0, validators_1.requireString)(a, 'url');
         await gate(ctx, 'navigate', { url });
-        return (0, envelopes_1.jsonResult)(await ctx.ex.navigate({ url, tabId: tabId(a), waitUntil: waitUntil(a) }));
+        const nav = await ctx.ex.navigate({ url, tabId: tabId(a), waitUntil: waitUntil(a) });
+        if (!authGuardOn(a, ctx.policy))
+            return (0, envelopes_1.jsonResult)(nav);
+        // Guard on: the check costs one snapshot round-trip after the navigation.
+        const snap = await ctx.ex.snapshot({ tabId: tabId(a), interactiveOnly: true, max: 200 });
+        (0, snapdiff_1.rememberSnapshot)(snapScope(a), snap);
+        return (0, envelopes_1.jsonResult)({ ...nav, ...authWallOf(ctx, snap, a) });
     },
     back: async (a, ctx) => {
         await gate(ctx, 'back', { tabId: tabId(a) });
-        return (0, envelopes_1.jsonResult)(await ctx.ex.back(tabId(a)));
+        const res = await ctx.ex.back(tabId(a));
+        await guardAuthWall(ctx, a);
+        return (0, envelopes_1.jsonResult)(res);
     },
     forward: async (a, ctx) => {
         await gate(ctx, 'forward', { tabId: tabId(a) });
-        return (0, envelopes_1.jsonResult)(await ctx.ex.forward(tabId(a)));
+        const res = await ctx.ex.forward(tabId(a));
+        await guardAuthWall(ctx, a);
+        return (0, envelopes_1.jsonResult)(res);
     },
     reload: async (a, ctx) => {
         await gate(ctx, 'reload', { tabId: tabId(a) });
-        return (0, envelopes_1.jsonResult)(await ctx.ex.reload({ tabId: tabId(a), waitUntil: waitUntil(a) }));
+        const res = await ctx.ex.reload({ tabId: tabId(a), waitUntil: waitUntil(a) });
+        await guardAuthWall(ctx, a);
+        return (0, envelopes_1.jsonResult)(res);
     },
     click: async (a, ctx) => {
         await gate(ctx, 'click', { tabId: tabId(a) });
@@ -453,10 +520,12 @@ exports.TOOL_HANDLERS = {
     },
     press: async (a, ctx) => {
         await gate(ctx, 'press', { tabId: tabId(a) });
-        return (0, envelopes_1.jsonResult)(await ctx.ex.press((0, validators_1.requireString)(a, 'key'), {
+        const res = await ctx.ex.press((0, validators_1.requireString)(a, 'key'), {
             tabId: tabId(a),
             modifiers: (0, validators_1.optionalStringArray)(a, 'modifiers'),
-        }));
+        });
+        await guardAuthWall(ctx, a); // Enter on a form is the classic way to land on a wall
+        return (0, envelopes_1.jsonResult)(res);
     },
     hover: async (a, ctx) => {
         await gate(ctx, 'hover', { tabId: tabId(a) });
@@ -536,14 +605,16 @@ exports.TOOL_HANDLERS = {
         const scope = snapScope(a);
         const previous = (0, snapdiff_1.lastSnapshot)(scope);
         const stored = (0, snapdiff_1.rememberSnapshot)(scope, snap);
+        const authWall = authWallOf(ctx, snap, a);
         if ((0, validators_1.optionalBoolean)(a, 'diff') !== true) {
-            return (0, envelopes_1.jsonResult)({ ...snap, snapshotId: stored.id });
+            return (0, envelopes_1.jsonResult)({ ...snap, snapshotId: stored.id, ...authWall });
         }
         const diff = (0, snapdiff_1.diffSnapshots)(previous, snap);
         return (0, envelopes_1.jsonResult)({
             url: snap.url,
             title: snap.title,
             snapshotId: stored.id,
+            ...authWall,
             ...diff,
             ...(diff.since === null
                 ? { note: 'no previous snapshot for this tab, so everything is reported as added' }
@@ -593,14 +664,19 @@ exports.TOOL_HANDLERS = {
     },
     wait_for: async (a, ctx) => {
         await gate(ctx, 'wait_for', { tabId: tabId(a) });
-        return (0, envelopes_1.jsonResult)(await ctx.ex.waitFor({
-            tabId: tabId(a),
-            ...frameOpts(a),
-            selector: (0, validators_1.optionalString)(a, 'selector'),
-            textContains: (0, validators_1.optionalString)(a, 'textContains'),
-            gone: (0, validators_1.optionalBoolean)(a, 'gone'),
-            timeoutMs: (0, validators_1.optionalNumber)(a, 'timeoutMs', { min: 0, max: 120_000 }),
-        }));
+        try {
+            return (0, envelopes_1.jsonResult)(await ctx.ex.waitFor({
+                tabId: tabId(a),
+                ...frameOpts(a),
+                selector: (0, validators_1.optionalString)(a, 'selector'),
+                textContains: (0, validators_1.optionalString)(a, 'textContains'),
+                gone: (0, validators_1.optionalBoolean)(a, 'gone'),
+                timeoutMs: (0, validators_1.optionalNumber)(a, 'timeoutMs', { min: 0, max: 120_000 }),
+            }));
+        }
+        catch (err) {
+            return reclassifyTimeout(ctx, a, err);
+        }
     },
     extract_links: async (a, ctx) => {
         await gate(ctx, 'get_text', { tabId: tabId(a) }); // read of page content
@@ -643,12 +719,14 @@ exports.TOOL_HANDLERS = {
             if (typeof val === 'string')
                 (0, validators_1.requireWithinLength)(val, `fields["${sel}"]`, validators_1.MAX_TEXT_LEN);
         }
-        return (0, envelopes_1.jsonResult)(await (0, helpers_1.fillForm)(ctx.ex, {
+        const res = await (0, helpers_1.fillForm)(ctx.ex, {
             ...frameOpts(a),
             fields: fields,
             submitSelector: (0, validators_1.optionalString)(a, 'submitSelector'),
             tabId: tabId(a),
-        }));
+        });
+        await guardAuthWall(ctx, a);
+        return (0, envelopes_1.jsonResult)(res);
     },
     download_file: async (a, ctx) => {
         await gate(ctx, 'download_file');
@@ -768,6 +846,18 @@ exports.TOOL_HANDLERS = {
         });
     },
     chrome_status: async (_a, ctx) => (0, envelopes_1.jsonResult)(ctx.ex.status()),
+    auth_check: async (a, ctx) => {
+        await gate(ctx, 'get_text', { tabId: tabId(a) }); // read of page structure
+        const snap = await ctx.ex.snapshot({ tabId: tabId(a), ...frameOpts(a), interactiveOnly: true, max: 200 });
+        const wall = (0, auth_wall_1.detectAuthWall)(snap);
+        failIfAuthWall(wall, snap.url, a, ctx.policy);
+        return (0, envelopes_1.jsonResult)({
+            url: snap.url,
+            title: snap.title,
+            authRequired: wall !== null,
+            ...(wall ? { confidence: wall.confidence, signals: wall.signals } : {}),
+        });
+    },
     // --- task workspace management (server-side; no browser needed) ---
     profile_use: async (a) => {
         // Snapshots are keyed by profile+tab, and a profile switch routes to a
@@ -877,7 +967,7 @@ function recordHistory(tool, rawArgs, ok, extra = {}) {
  */
 const RETRY_SAFE_TOOLS = new Set([
     'tabs_list', 'chrome_status',
-    'get_text', 'get_html', 'snapshot', 'get_cookies',
+    'get_text', 'get_html', 'snapshot', 'get_cookies', 'auth_check',
     'extract_links', 'read_as_markdown', 'screenshot',
     'wait_for', 'navigate', 'reload',
     'frames_list', 'print_pdf',

package/dist/src/security/policy.d.ts

@@ -32,6 +32,10 @@ export interface Policy extends WirePolicy {
     redact?: boolean;
     /** Extra redaction patterns (regex sources) supplied by the operator. */
     redactPatterns?: string[];
+    /** `--fail-on-auth-wall`: every navigating tool and action fails with
+     *  `AUTH_REQUIRED` when the page it lands on is a high-confidence sign-in
+     *  wall, so an expired session is never scored as some other failure. */
+    failOnAuthWall?: boolean;
 }
 /** The SAFE default: deny everything until the user opts in. */
 export declare const DEFAULT_POLICY: Readonly<Policy>;

package/dist/src/security/policy.js

@@ -43,6 +43,7 @@ exports.DEFAULT_POLICY = Object.freeze({
     allowObservers: false,
     redact: false,
     redactPatterns: [],
+    failOnAuthWall: false,
 });
 /** Merge a partial (from a policy file and/or CLI flags) over the safe default. */
 function resolvePolicy(partial) {
@@ -57,6 +58,7 @@ function resolvePolicy(partial) {
         allowObservers: partial?.allowObservers ?? exports.DEFAULT_POLICY.allowObservers,
         redact: partial?.redact ?? exports.DEFAULT_POLICY.redact,
         redactPatterns: partial?.redactPatterns ?? [...(exports.DEFAULT_POLICY.redactPatterns ?? [])],
+        failOnAuthWall: partial?.failOnAuthWall ?? exports.DEFAULT_POLICY.failOnAuthWall,
     };
 }
 // ---------------------------------------------------------------------------

package/docs/BLUEPRINT.md

@@ -350,7 +350,7 @@ export type ExecutorErrorCode =
 
 ## 5. The Complete MCP Tool Surface
 
-38 tools. `readOnly` is metadata (not a JSON-Schema field) consumed by the host
+39 tools. `readOnly` is metadata (not a JSON-Schema field) consumed by the host
 and by **safe-mode** (shipped in v1, default ON). Every handler:
 `withReadyExecutor()` → validate args (`requireTarget` for selector|ref) →
 **`policy.assertUrlAllowed(currentTabUrl, method)`** → call executor/helper →

package/extension-dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "MCP Extension for Chrome",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Lets a local chrome-mcp server drive this browser. Pair it with the server's handshake token.",
   "homepage_url": "https://github.com/Mehmoodqureshi/chrome-mcp",
   "minimum_chrome_version": "116",

package/package.json

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