agent-browser-stealth 0.15.1-fork.6 → 0.15.1-fork.7

package/dist/action-policy.d.ts

@@ -0,0 +1,14 @@
+export interface ActionPolicy {
+    default: 'allow' | 'deny';
+    allow?: string[];
+    deny?: string[];
+}
+export type PolicyDecision = 'allow' | 'deny' | 'confirm';
+export declare const KNOWN_CATEGORIES: Set<string>;
+export declare function getActionCategory(action: string): string;
+export declare function loadPolicyFile(policyPath: string): ActionPolicy;
+export declare function initPolicyReloader(policyPath: string, policy: ActionPolicy): void;
+export declare function reloadPolicyIfChanged(): ActionPolicy | null;
+export declare function checkPolicy(action: string, policy: ActionPolicy | null, confirmCategories: Set<string>): PolicyDecision;
+export declare function describeAction(action: string, command: Record<string, unknown>): string;
+//# sourceMappingURL=action-policy.d.ts.map

package/dist/action-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-policy.d.ts","sourceRoot":"","sources":["../src/action-policy.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AA4K1D,eAAO,MAAM,gBAAgB,aAE5B,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAwB/D;AAQD,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAIjF;AAED,wBAAgB,qBAAqB,IAAI,YAAY,GAAG,IAAI,CAkB3D;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,GAAG,IAAI,EAC3B,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,GAC7B,cAAc,CAkBhB;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAyBvF"}

package/dist/action-policy.js

@@ -0,0 +1,253 @@
+import { readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+const ACTION_CATEGORIES = {
+    navigate: 'navigate',
+    back: 'navigate',
+    forward: 'navigate',
+    reload: 'navigate',
+    tab_new: 'navigate',
+    click: 'click',
+    dblclick: 'click',
+    tap: 'click',
+    fill: 'fill',
+    type: 'fill',
+    // The `keyboard` action is a compound command that dispatches to sub-actions
+    // (type, inserttext, press, down, up). Its primary use is text input, so it
+    // maps to 'fill'. The interact-like sub-actions (press, down, up) are less
+    // common and don't have separate top-level action names in the protocol.
+    keyboard: 'fill',
+    inserttext: 'fill',
+    select: 'fill',
+    multiselect: 'fill',
+    check: 'fill',
+    uncheck: 'fill',
+    clear: 'fill',
+    selectall: 'fill',
+    setvalue: 'fill',
+    download: 'download',
+    waitfordownload: 'download',
+    upload: 'upload',
+    evaluate: 'eval',
+    evalhandle: 'eval',
+    addscript: 'eval',
+    addinitscript: 'eval',
+    snapshot: 'snapshot',
+    screenshot: 'snapshot',
+    pdf: 'snapshot',
+    diff_snapshot: 'snapshot',
+    diff_screenshot: 'snapshot',
+    diff_url: 'snapshot',
+    scroll: 'scroll',
+    scrollintoview: 'scroll',
+    wait: 'wait',
+    waitforurl: 'wait',
+    waitforloadstate: 'wait',
+    waitforfunction: 'wait',
+    gettext: 'get',
+    content: 'get',
+    innerhtml: 'get',
+    innertext: 'get',
+    inputvalue: 'get',
+    url: 'get',
+    title: 'get',
+    getattribute: 'get',
+    count: 'get',
+    boundingbox: 'get',
+    styles: 'get',
+    isvisible: 'get',
+    isenabled: 'get',
+    ischecked: 'get',
+    responsebody: 'get',
+    route: 'network',
+    unroute: 'network',
+    requests: 'network',
+    state_save: 'state',
+    state_load: 'state',
+    cookies_set: 'state',
+    storage_set: 'state',
+    credentials: 'state',
+    hover: 'interact',
+    focus: 'interact',
+    drag: 'interact',
+    press: 'interact',
+    keydown: 'interact',
+    keyup: 'interact',
+    mousemove: 'interact',
+    mousedown: 'interact',
+    mouseup: 'interact',
+    wheel: 'interact',
+    dispatch: 'interact',
+    // These are always allowed (internal/meta operations)
+    launch: '_internal',
+    close: '_internal',
+    tab_list: '_internal',
+    tab_switch: '_internal',
+    tab_close: '_internal',
+    window_new: '_internal',
+    frame: '_internal',
+    mainframe: '_internal',
+    dialog: '_internal',
+    session: '_internal',
+    console: '_internal',
+    errors: '_internal',
+    cookies_get: '_internal',
+    cookies_clear: '_internal',
+    storage_get: '_internal',
+    storage_clear: '_internal',
+    state_list: '_internal',
+    state_show: '_internal',
+    state_clear: '_internal',
+    state_clean: '_internal',
+    state_rename: '_internal',
+    highlight: '_internal',
+    bringtofront: '_internal',
+    trace_start: '_internal',
+    trace_stop: '_internal',
+    har_start: '_internal',
+    har_stop: '_internal',
+    video_start: '_internal',
+    video_stop: '_internal',
+    recording_start: '_internal',
+    recording_stop: '_internal',
+    recording_restart: '_internal',
+    profiler_start: '_internal',
+    profiler_stop: '_internal',
+    clipboard: '_internal',
+    viewport: '_internal',
+    useragent: '_internal',
+    device: '_internal',
+    geolocation: '_internal',
+    permissions: '_internal',
+    emulatemedia: '_internal',
+    offline: '_internal',
+    headers: '_internal',
+    addstyle: 'eval',
+    expose: 'eval',
+    timezone: '_internal',
+    locale: '_internal',
+    pause: '_internal',
+    setcontent: 'eval',
+    screencast_start: '_internal',
+    screencast_stop: '_internal',
+    input_mouse: '_internal',
+    input_keyboard: '_internal',
+    input_touch: '_internal',
+    auth_save: '_internal',
+    auth_login: '_internal',
+    auth_list: '_internal',
+    auth_delete: '_internal',
+    auth_show: '_internal',
+    confirm: '_internal',
+    deny: '_internal',
+    // Find/semantic locator actions (read-only element resolution)
+    getbyrole: 'get',
+    getbytext: 'get',
+    getbylabel: 'get',
+    getbyplaceholder: 'get',
+    getbyalttext: 'get',
+    getbytitle: 'get',
+    getbytestid: 'get',
+    nth: 'get',
+};
+// User-facing categories used in policy files. '_internal' is excluded because
+// internal actions always bypass policy. 'unknown' is intentionally not a value
+// in ACTION_CATEGORIES -- it is only the fallback return of getActionCategory()
+// for unrecognized actions. If a user puts "unknown" in a policy file,
+// loadPolicyFile will warn about it as unrecognized, which is correct.
+export const KNOWN_CATEGORIES = new Set(Object.values(ACTION_CATEGORIES).filter((c) => c !== '_internal'));
+export function getActionCategory(action) {
+    return ACTION_CATEGORIES[action] ?? 'unknown';
+}
+export function loadPolicyFile(policyPath) {
+    const resolved = resolve(policyPath);
+    const content = readFileSync(resolved, 'utf-8');
+    const policy = JSON.parse(content);
+    if (policy.default !== 'allow' && policy.default !== 'deny') {
+        throw new Error(`Invalid action policy: "default" must be "allow" or "deny", got "${policy.default}"`);
+    }
+    for (const list of [policy.allow, policy.deny]) {
+        if (!list)
+            continue;
+        for (const category of list) {
+            if (!KNOWN_CATEGORIES.has(category)) {
+                console.warn(`[agent-browser] Warning: unrecognized action category "${category}" in policy file. ` +
+                    `Known categories: ${[...KNOWN_CATEGORIES].sort().join(', ')}`);
+            }
+        }
+    }
+    return policy;
+}
+let cachedPolicyPath = null;
+let cachedPolicyMtimeMs = 0;
+let cachedPolicy = null;
+const RELOAD_CHECK_INTERVAL_MS = 5_000;
+let lastCheckMs = 0;
+export function initPolicyReloader(policyPath, policy) {
+    cachedPolicyPath = resolve(policyPath);
+    cachedPolicyMtimeMs = statSync(cachedPolicyPath).mtimeMs;
+    cachedPolicy = policy;
+}
+export function reloadPolicyIfChanged() {
+    if (!cachedPolicyPath)
+        return cachedPolicy;
+    const now = Date.now();
+    if (now - lastCheckMs < RELOAD_CHECK_INTERVAL_MS)
+        return cachedPolicy;
+    lastCheckMs = now;
+    try {
+        const currentMtime = statSync(cachedPolicyPath).mtimeMs;
+        if (currentMtime !== cachedPolicyMtimeMs) {
+            cachedPolicy = loadPolicyFile(cachedPolicyPath);
+            cachedPolicyMtimeMs = currentMtime;
+        }
+    }
+    catch {
+        // File may have been removed; keep using cached policy
+    }
+    return cachedPolicy;
+}
+export function checkPolicy(action, policy, confirmCategories) {
+    const category = getActionCategory(action);
+    // Internal actions are always allowed
+    if (category === '_internal')
+        return 'allow';
+    // Explicit deny takes precedence over confirmation
+    if (policy?.deny?.includes(category))
+        return 'deny';
+    // Check if this category requires confirmation
+    if (confirmCategories.has(category))
+        return 'confirm';
+    if (!policy)
+        return 'allow';
+    // Explicit allow list
+    if (policy.allow?.includes(category))
+        return 'allow';
+    return policy.default;
+}
+export function describeAction(action, command) {
+    const category = getActionCategory(action);
+    switch (action) {
+        case 'navigate':
+            return `Navigate to ${command.url}`;
+        case 'evaluate':
+        case 'evalhandle':
+            return `Evaluate JavaScript: ${String(command.script ?? '').slice(0, 80)}`;
+        case 'fill':
+            return `Fill ${command.selector}`;
+        case 'type':
+            return `Type into ${command.selector}`;
+        case 'click':
+            return `Click ${command.selector}`;
+        case 'dblclick':
+            return `Double-click ${command.selector}`;
+        case 'tap':
+            return `Tap ${command.selector}`;
+        case 'download':
+            return `Download via ${command.selector} to ${command.path}`;
+        case 'upload':
+            return `Upload files to ${command.selector}`;
+        default:
+            return `${category}: ${action}`;
+    }
+}
+//# sourceMappingURL=action-policy.js.map

package/dist/action-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-policy.js","sourceRoot":"","sources":["../src/action-policy.ts"],"names":[],"mappings":"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"}

package/dist/actions.d.ts

@@ -1,5 +1,5 @@
 import type { BrowserManager, ScreencastFrame } from './browser.js';
-import type { Command, Response } from './types.js';
+import type { Command, Response, RiskSignal } from './types.js';
 /**
  * Set the callback for screencast frames
  * This is called by the daemon to set up frame streaming
@@ -14,4 +14,8 @@ export declare function toAIFriendlyError(error: unknown, selector: string): Err
  * Execute a command and return a response
  */
 export declare function executeCommand(command: Command, browser: BrowserManager): Promise<Response>;
+/**
+ * Detect verification/captcha interstitials and return structured risk evidence.
+ */
+export declare function detectRiskSignals(url: string, title: string): RiskSignal[];
 //# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAUpE,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EAmIT,MAAM,YAAY,CAAC;AAQpB;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,CAAC,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC,GAAG,IAAI,GAClD,IAAI,CAEN;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,CAqDzE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAuRjG"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAUpE,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EAmIR,UAAU,EACX,MAAM,YAAY,CAAC;AAQpB;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,CAAC,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC,GAAG,IAAI,GAClD,IAAI,CAEN;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,CAqDzE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAuRjG;AAyGD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE,CA8C1E"}

package/dist/actions.js

@@ -359,65 +359,114 @@ async function handleNavigate(command, browser) {
     await page.goto(command.url, {
         waitUntil: command.waitUntil ?? 'load',
     });
-    // Detect captcha/verification pages and retry with backoff
-    const finalUrl = page.url();
-    const title = await page.title();
-    const captchaDetected = isCaptchaPage(finalUrl, title);
-    if (captchaDetected) {
-        const maxRetries = 2;
-        for (let attempt = 1; attempt <= maxRetries; attempt++) {
-            const backoff = 3000 + Math.random() * 4000;
-            await page.waitForTimeout(Math.round(backoff));
-            await page.goto(command.url, {
-                waitUntil: command.waitUntil ?? 'load',
-            });
-            const retryUrl = page.url();
-            const retryTitle = await page.title();
-            if (!isCaptchaPage(retryUrl, retryTitle)) {
-                return successResponse(command.id, {
-                    url: retryUrl,
-                    title: retryTitle,
-                });
-            }
-        }
-        // All retries exhausted -- return the page as-is with a warning
+    const riskMode = command.riskMode ?? 'warn';
+    if (riskMode === 'off') {
         return successResponse(command.id, {
             url: page.url(),
             title: await page.title(),
-            warning: 'Captcha/verification page detected. Try --headed mode or use --session-name for state persistence.',
         });
     }
+    // Detect risk interstitials (captcha/verification) and handle by risk mode.
+    const finalUrl = page.url();
+    const title = await page.title();
+    let encounteredSignals = detectRiskSignals(finalUrl, title);
+    if (encounteredSignals.length === 0) {
+        return successResponse(command.id, {
+            url: finalUrl,
+            title,
+        });
+    }
+    if (riskMode === 'block') {
+        const first = encounteredSignals[0];
+        return errorResponse(command.id, `Navigation blocked by risk-mode=block: ${first.code} (${first.source}="${first.evidence}")`);
+    }
+    const maxRetries = 2;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        const backoff = 3000 + Math.random() * 4000;
+        await page.waitForTimeout(Math.round(backoff));
+        await page.goto(command.url, {
+            waitUntil: command.waitUntil ?? 'load',
+        });
+        const retryUrl = page.url();
+        const retryTitle = await page.title();
+        const retrySignals = detectRiskSignals(retryUrl, retryTitle);
+        if (retrySignals.length === 0) {
+            return successResponse(command.id, {
+                url: retryUrl,
+                title: retryTitle,
+                warning: 'Risk interstitial detected and recovered after retry. Review riskSignals for evidence.',
+                riskSignals: encounteredSignals,
+            });
+        }
+        encounteredSignals = mergeRiskSignals(encounteredSignals, retrySignals);
+    }
+    // All retries exhausted -- return the page as-is with a warning and evidence.
     return successResponse(command.id, {
-        url: finalUrl,
-        title,
+        url: page.url(),
+        title: await page.title(),
+        warning: 'Captcha/verification page detected. Try --headed mode or use --session-name for state persistence.',
+        riskSignals: encounteredSignals,
     });
 }
-function isCaptchaPage(url, title) {
+function mergeRiskSignals(current, next) {
+    const merged = new Map();
+    for (const signal of [...current, ...next]) {
+        const key = `${signal.code}|${signal.source}|${signal.evidence}`;
+        if (!merged.has(key) || (merged.get(key)?.confidence ?? 0) < signal.confidence) {
+            merged.set(key, signal);
+        }
+    }
+    return [...merged.values()];
+}
+/**
+ * Detect verification/captcha interstitials and return structured risk evidence.
+ */
+export function detectRiskSignals(url, title) {
     const lowerUrl = url.toLowerCase();
     const lowerTitle = title.toLowerCase();
-    const captchaPatterns = [
-        '/verify/captcha',
-        '/captcha',
-        '/challenge',
-        'scene=crawler',
-        'scene=anti_bot',
-        'recaptcha',
-        'hcaptcha',
+    const urlPatterns = [
+        { pattern: '/verify/captcha', code: 'captcha_interstitial', confidence: 0.98 },
+        { pattern: '/captcha', code: 'captcha_interstitial', confidence: 0.95 },
+        { pattern: '/challenge', code: 'verification_interstitial', confidence: 0.93 },
+        { pattern: 'scene=crawler', code: 'bot_challenge', confidence: 0.99 },
+        { pattern: 'scene=anti_bot', code: 'bot_challenge', confidence: 0.99 },
+        { pattern: 'recaptcha', code: 'captcha_interstitial', confidence: 0.97 },
+        { pattern: 'hcaptcha', code: 'captcha_interstitial', confidence: 0.97 },
     ];
     const titlePatterns = [
-        'verify',
-        'captcha',
-        'challenge',
-        'attention required',
-        'just a moment',
-        'checking your browser',
-        'access denied',
-        '驗證',
-        '验证',
-        '人机验证',
+        { pattern: 'verify', code: 'verification_interstitial', confidence: 0.78 },
+        { pattern: 'captcha', code: 'captcha_interstitial', confidence: 0.9 },
+        { pattern: 'challenge', code: 'verification_interstitial', confidence: 0.8 },
+        { pattern: 'attention required', code: 'verification_interstitial', confidence: 0.96 },
+        { pattern: 'just a moment', code: 'verification_interstitial', confidence: 0.95 },
+        { pattern: 'checking your browser', code: 'verification_interstitial', confidence: 0.97 },
+        { pattern: 'access denied', code: 'access_gate', confidence: 0.86 },
+        { pattern: '驗證', code: 'verification_interstitial', confidence: 0.88 },
+        { pattern: '验证', code: 'verification_interstitial', confidence: 0.88 },
+        { pattern: '人机验证', code: 'captcha_interstitial', confidence: 0.95 },
     ];
-    return (captchaPatterns.some((p) => lowerUrl.includes(p)) ||
-        titlePatterns.some((p) => lowerTitle.includes(p)));
+    const signals = [];
+    for (const item of urlPatterns) {
+        if (lowerUrl.includes(item.pattern)) {
+            signals.push({
+                code: item.code,
+                source: 'url',
+                evidence: item.pattern,
+                confidence: item.confidence,
+            });
+        }
+    }
+    for (const item of titlePatterns) {
+        if (lowerTitle.includes(item.pattern)) {
+            signals.push({
+                code: item.code,
+                source: 'title',
+                evidence: item.pattern,
+                confidence: item.confidence,
+            });
+        }
+    }
+    return mergeRiskSignals([], signals);
 }
 function bezierPoint(t, p0, p1, p2, p3) {
     const u = 1 - t;
@@ -746,36 +795,36 @@ async function handleWait(command, browser) {
 }
 async function handleScroll(command, browser) {
     const page = browser.getPage();
+    let deltaX = command.x ?? 0;
+    let deltaY = command.y ?? 0;
+    const hasExplicitDelta = command.x !== undefined || command.y !== undefined;
+    if (command.direction) {
+        const amount = command.amount ?? 100;
+        switch (command.direction) {
+            case 'up':
+                deltaY = -amount;
+                break;
+            case 'down':
+                deltaY = amount;
+                break;
+            case 'left':
+                deltaX = -amount;
+                break;
+            case 'right':
+                deltaX = amount;
+                break;
+        }
+    }
     if (command.selector) {
         const element = browser.getLocator(command.selector);
         await element.scrollIntoViewIfNeeded();
-        if (command.x !== undefined || command.y !== undefined) {
+        if (hasExplicitDelta || deltaX !== 0 || deltaY !== 0) {
             await element.evaluate((el, { x, y }) => {
-                el.scrollBy(x ?? 0, y ?? 0);
-            }, { x: command.x, y: command.y });
+                el.scrollBy(x, y);
+            }, { x: deltaX, y: deltaY });
         }
     }
     else {
-        // Scroll the page
-        let deltaX = command.x ?? 0;
-        let deltaY = command.y ?? 0;
-        if (command.direction) {
-            const amount = command.amount ?? 100;
-            switch (command.direction) {
-                case 'up':
-                    deltaY = -amount;
-                    break;
-                case 'down':
-                    deltaY = amount;
-                    break;
-                case 'left':
-                    deltaX = -amount;
-                    break;
-                case 'right':
-                    deltaX = amount;
-                    break;
-            }
-        }
         await page.evaluate(`window.scrollBy(${deltaX}, ${deltaY})`);
     }
     return successResponse(command.id, { scrolled: true });
@@ -993,9 +1042,16 @@ async function handleCookiesGet(command, browser) {
 async function handleCookiesSet(command, browser) {
     const page = browser.getPage();
     const context = page.context();
-    // Auto-fill URL for cookies that don't have domain/path/url set
+    // Playwright requires either `url` or a complete `domain` + `path` pair.
+    // If none are provided, we default to the current page URL.
     const pageUrl = page.url();
     const cookies = command.cookies.map((cookie) => {
+        const hasUrl = Boolean(cookie.url);
+        const hasDomain = Boolean(cookie.domain);
+        const hasPath = Boolean(cookie.path);
+        if (!hasUrl && hasDomain !== hasPath) {
+            throw new Error(`Invalid cookie "${cookie.name}": provide either url, or both domain and path`);
+        }
         if (!cookie.url && !cookie.domain && !cookie.path) {
             return { ...cookie, url: pageUrl };
         }