camofox-browser 2.1.0 → 2.4.1

package/dist/src/services/tab.js

@@ -7,7 +7,12 @@ exports.clearTabLock = clearTabLock;
 exports.clearAllTabLocks = clearAllTabLocks;
 exports.calculateTypeTimeoutMs = calculateTypeTimeoutMs;
 exports.safePageClose = safePageClose;
+exports.throwBlockedNavigationErrorIfPresent = throwBlockedNavigationErrorIfPresent;
+exports.flushBlockedNavigationError = flushBlockedNavigationError;
+exports.withBlockedNavigationTracking = withBlockedNavigationTracking;
 exports.validateUrl = validateUrl;
+exports.validateNavigationUrl = validateNavigationUrl;
+exports.navigateWithSafetyGuard = navigateWithSafetyGuard;
 exports.annotateAriaYamlWithRefs = annotateAriaYamlWithRefs;
 exports.waitForPageReady = waitForPageReady;
 exports.dismissConsentDialogs = dismissConsentDialogs;
@@ -19,6 +24,7 @@ exports.refToLocator = refToLocator;
 exports.createTabState = createTabState;
 exports.navigateTab = navigateTab;
 exports.snapshotTab = snapshotTab;
+exports.buildSnapshotPayload = buildSnapshotPayload;
 exports.clickTab = clickTab;
 exports.smartFill = smartFill;
 exports.typeTab = typeTab;
@@ -33,10 +39,16 @@ exports.refreshTab = refreshTab;
 exports.getLinks = getLinks;
 exports.screenshotTab = screenshotTab;
 exports.waitTab = waitTab;
+const promises_1 = require("node:dns/promises");
+const node_net_1 = require("node:net");
 const selector_1 = require("../cli/utils/selector");
 const macros_1 = require("../utils/macros");
+const config_1 = require("../utils/config");
+const snapshot_1 = require("../utils/snapshot");
 const logging_1 = require("../middleware/logging");
 const ALLOWED_URL_SCHEMES = ['http:', 'https:'];
+const CONFIG = (0, config_1.loadConfig)();
+const METADATA_HOSTNAMES = new Set(['metadata.google.internal']);
 // Selective set of actionable roles worth indexing as refs.
 const INTERACTIVE_ROLES = [
     'button',
@@ -61,17 +73,26 @@ const INTERACTIVE_ROLES = [
 ];
 // Patterns to skip (date pickers, calendar widgets)
 const SKIP_PATTERNS = [/date/i, /calendar/i, /picker/i, /datepicker/i];
-const DEFAULT_MAX_SNAPSHOT_NODES = 2000;
-const parsedMaxSnapshotNodes = Number.parseInt(process.env.CAMOFOX_MAX_SNAPSHOT_NODES || String(DEFAULT_MAX_SNAPSHOT_NODES), 10);
-const MAX_SNAPSHOT_NODES = Number.isFinite(parsedMaxSnapshotNodes) && parsedMaxSnapshotNodes > 0
-    ? parsedMaxSnapshotNodes
-    : DEFAULT_MAX_SNAPSHOT_NODES;
+const MAX_SNAPSHOT_NODES = CONFIG.maxSnapshotNodes;
 const MAX_EVAL_TIMEOUT = 300000;
 const DEFAULT_EVAL_TIMEOUT = 5000;
 const MAX_EVAL_EXTENDED_TIMEOUT = 300000;
 const DEFAULT_EVAL_EXTENDED_TIMEOUT = 30000;
 const MAX_RESULT_SIZE = 1048576; // 1MB
-const CONSOLE_BUFFER_SIZE = Math.max(100, parseInt(process.env.CAMOFOX_CONSOLE_BUFFER_SIZE || '1000', 10));
+const CONSOLE_BUFFER_SIZE = CONFIG.consoleBufferSize;
+const POST_ACTION_NAVIGATION_SETTLE_MS = 500;
+const ACTION_TRACKER_POLL_MS = 10;
+const navigationGuardHandlers = new WeakMap();
+const blockedNavigationErrors = new WeakMap();
+const trackedBlockedNavigationErrors = new WeakMap();
+const popupOpenerPages = new WeakMap();
+const inFlightGuardChecks = new WeakMap();
+const trackedInFlightGuardChecks = new WeakMap();
+const trackedPendingCounts = new WeakMap();
+const actionTrackerInstalledPages = new WeakSet();
+const actionTrackerBindingContexts = new WeakSet();
+const actionTrackerTokens = new WeakMap();
+const activeTrackedActionTokens = new WeakMap();
 exports.LONG_TEXT_THRESHOLD = 400;
 exports.TYPE_TIMEOUT_BASE_MS = 10000;
 exports.TYPE_TIMEOUT_PER_CHAR_MS = 80;
@@ -149,18 +170,606 @@ async function safePageClose(page) {
         console.warn(`[camofox] page close failed: ${message}`);
     }
 }
-function validateUrl(url) {
+function normalizeHostname(hostname) {
+    return hostname.trim().replace(/^\[|\]$/g, '').replace(/\.$/, '').toLowerCase();
+}
+function parseIpv4Octets(hostname) {
+    const parts = hostname.split('.');
+    if (parts.length !== 4)
+        return null;
+    const octets = parts.map((part) => Number.parseInt(part, 10));
+    if (octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255))
+        return null;
+    return octets;
+}
+function isBlockedIpv4(hostname) {
+    const octets = parseIpv4Octets(hostname);
+    if (!octets)
+        return false;
+    const [a, b] = octets;
+    if (a === 0 || a === 10 || a === 127)
+        return true;
+    if (a === 100 && b >= 64 && b <= 127)
+        return true;
+    if (a === 169 && b === 254)
+        return true;
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    if (a === 192 && b === 168)
+        return true;
+    if (a === 198 && (b === 18 || b === 19))
+        return true;
+    return false;
+}
+function isBlockedIpv6(hostname) {
+    const normalized = normalizeHostname(hostname);
+    if (normalized === '::1')
+        return true;
+    const nat64DottedMatch = normalized.match(/^64:ff9b::(\d+\.\d+\.\d+\.\d+)$/i);
+    if (nat64DottedMatch) {
+        return isBlockedIpv4(nat64DottedMatch[1]);
+    }
+    const nat64HexMatch = normalized.match(/^64:ff9b::([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+    if (nat64HexMatch) {
+        const high = Number.parseInt(nat64HexMatch[1], 16);
+        const low = Number.parseInt(nat64HexMatch[2], 16);
+        if (Number.isFinite(high) && Number.isFinite(low)) {
+            const mappedIpv4 = [
+                (high >> 8) & 0xff,
+                high & 0xff,
+                (low >> 8) & 0xff,
+                low & 0xff,
+            ].join('.');
+            return isBlockedIpv4(mappedIpv4);
+        }
+    }
+    const mappedIpv4Match = normalized.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+    if (mappedIpv4Match) {
+        return isBlockedIpv4(mappedIpv4Match[1]);
+    }
+    const mappedIpv4HexMatch = normalized.match(/^::ffff:([0-9a-f]{1,4})(?::([0-9a-f]{1,4}))?$/i);
+    if (mappedIpv4HexMatch) {
+        const high = Number.parseInt(mappedIpv4HexMatch[1], 16);
+        const low = Number.parseInt(mappedIpv4HexMatch[2] || '0', 16);
+        if (Number.isFinite(high) && Number.isFinite(low)) {
+            const mappedIpv4 = [
+                (high >> 8) & 0xff,
+                high & 0xff,
+                (low >> 8) & 0xff,
+                low & 0xff,
+            ].join('.');
+            return isBlockedIpv4(mappedIpv4);
+        }
+    }
+    const firstHextetRaw = normalized.split(':', 1)[0] || '0';
+    const firstHextet = Number.parseInt(firstHextetRaw, 16);
+    if (!Number.isFinite(firstHextet))
+        return false;
+    if ((firstHextet & 0xfe00) === 0xfc00)
+        return true;
+    if ((firstHextet & 0xffc0) === 0xfe80)
+        return true;
+    return false;
+}
+function isBlockedPrivateNetworkHostname(hostname) {
+    const normalized = normalizeHostname(hostname);
+    if (normalized === 'localhost' || normalized === 'localhost.localdomain')
+        return true;
+    if (METADATA_HOSTNAMES.has(normalized))
+        return true;
+    const ipVersion = (0, node_net_1.isIP)(normalized);
+    if (ipVersion === 4)
+        return isBlockedIpv4(normalized);
+    if (ipVersion === 6)
+        return isBlockedIpv6(normalized);
+    return false;
+}
+function createNavigationBlockError(message) {
+    const error = new Error(message);
+    error.statusCode = 400;
+    return error;
+}
+function takeBlockedNavigationError(page) {
+    const message = blockedNavigationErrors.get(page);
+    if (!message)
+        return null;
+    blockedNavigationErrors.delete(page);
+    return createNavigationBlockError(message);
+}
+function setTrackedBlockedNavigationError(page, token, message) {
+    const existing = trackedBlockedNavigationErrors.get(page) || new Map();
+    existing.set(token, message);
+    trackedBlockedNavigationErrors.set(page, existing);
+}
+function takeTrackedBlockedNavigationError(page, token) {
+    const existing = trackedBlockedNavigationErrors.get(page);
+    const message = existing?.get(token);
+    if (!message)
+        return null;
+    existing?.delete(token);
+    if (existing && existing.size === 0) {
+        trackedBlockedNavigationErrors.delete(page);
+    }
+    return createNavigationBlockError(message);
+}
+function rethrowWithBlockedNavigationError(page, err) {
+    const blockedError = takeBlockedNavigationError(page);
+    if (blockedError)
+        throw blockedError;
+    throw err;
+}
+function rethrowWithTrackedBlockedNavigationError(page, token, err) {
+    const blockedError = takeTrackedBlockedNavigationError(page, token);
+    if (blockedError)
+        throw blockedError;
+    throw err;
+}
+function throwBlockedNavigationErrorIfPresent(page) {
+    const blockedError = takeBlockedNavigationError(page);
+    if (blockedError)
+        throw blockedError;
+}
+function throwTrackedBlockedNavigationErrorIfPresent(page, token) {
+    const blockedError = takeTrackedBlockedNavigationError(page, token);
+    if (blockedError)
+        throw blockedError;
+}
+function clearBlockedNavigationError(page) {
+    blockedNavigationErrors.delete(page);
+}
+function installActionTrackerScript() {
+    const browserGlobal = globalThis;
+    if (browserGlobal.__camofoxActionTracker)
+        return;
+    const state = {
+        activeToken: 0,
+        pendingCounts: new Map(),
+        timeoutTokens: new Map(),
+        intervalTokens: new Map(),
+        rafTokens: new Map(),
+    };
+    const increment = (token) => {
+        state.pendingCounts.set(token, (state.pendingCounts.get(token) || 0) + 1);
+        void browserGlobal.__camofoxUpdatePendingCount?.(token, state.pendingCounts.get(token) || 0);
+    };
+    const decrement = (token) => {
+        const next = (state.pendingCounts.get(token) || 0) - 1;
+        if (next > 0) {
+            state.pendingCounts.set(token, next);
+        }
+        else {
+            state.pendingCounts.delete(token);
+        }
+        void browserGlobal.__camofoxUpdatePendingCount?.(token, state.pendingCounts.get(token) || 0);
+    };
+    const syncActiveToken = (token) => {
+        state.activeToken = token;
+        void browserGlobal.__camofoxUpdateActiveToken?.(token);
+    };
+    const withToken = (token, fn) => {
+        const previousToken = state.activeToken;
+        syncActiveToken(token);
+        try {
+            return fn();
+        }
+        finally {
+            syncActiveToken(previousToken);
+        }
+    };
+    const runHandler = (handler, args) => {
+        if (typeof handler === 'function') {
+            return handler(...args);
+        }
+        return browserGlobal.eval(String(handler));
+    };
+    const originalSetTimeout = browserGlobal.setTimeout.bind(browserGlobal);
+    const originalClearTimeout = browserGlobal.clearTimeout.bind(browserGlobal);
+    const originalSetInterval = browserGlobal.setInterval.bind(browserGlobal);
+    const originalClearInterval = browserGlobal.clearInterval.bind(browserGlobal);
+    const originalRequestAnimationFrame = typeof browserGlobal.requestAnimationFrame === 'function'
+        ? browserGlobal.requestAnimationFrame.bind(browserGlobal)
+        : null;
+    const originalCancelAnimationFrame = typeof browserGlobal.cancelAnimationFrame === 'function'
+        ? browserGlobal.cancelAnimationFrame.bind(browserGlobal)
+        : null;
+    const originalQueueMicrotask = typeof browserGlobal.queueMicrotask === 'function'
+        ? browserGlobal.queueMicrotask.bind(browserGlobal)
+        : null;
+    browserGlobal.setTimeout = (handler, delay, ...args) => {
+        const token = state.activeToken;
+        if (!token) {
+            return originalSetTimeout(handler, delay, ...args);
+        }
+        increment(token);
+        let timeoutId;
+        const wrapped = (...callbackArgs) => {
+            const trackedToken = state.timeoutTokens.get(timeoutId) || token;
+            state.timeoutTokens.delete(timeoutId);
+            try {
+                return withToken(trackedToken, () => runHandler(handler, callbackArgs));
+            }
+            finally {
+                decrement(trackedToken);
+            }
+        };
+        timeoutId = originalSetTimeout(wrapped, delay, ...args);
+        state.timeoutTokens.set(timeoutId, token);
+        return timeoutId;
+    };
+    browserGlobal.clearTimeout = (timeoutId) => {
+        const token = state.timeoutTokens.get(timeoutId);
+        if (token) {
+            state.timeoutTokens.delete(timeoutId);
+            decrement(token);
+        }
+        return originalClearTimeout(timeoutId);
+    };
+    browserGlobal.setInterval = (handler, delay, ...args) => {
+        const token = state.activeToken;
+        if (!token) {
+            return originalSetInterval(handler, delay, ...args);
+        }
+        let intervalId;
+        const wrapped = (...callbackArgs) => {
+            const trackedToken = state.intervalTokens.get(intervalId) || token;
+            increment(trackedToken);
+            try {
+                return withToken(trackedToken, () => runHandler(handler, callbackArgs));
+            }
+            finally {
+                decrement(trackedToken);
+            }
+        };
+        intervalId = originalSetInterval(wrapped, delay, ...args);
+        state.intervalTokens.set(intervalId, token);
+        return intervalId;
+    };
+    browserGlobal.clearInterval = (intervalId) => {
+        state.intervalTokens.delete(intervalId);
+        return originalClearInterval(intervalId);
+    };
+    if (originalRequestAnimationFrame && originalCancelAnimationFrame) {
+        browserGlobal.requestAnimationFrame = (callback) => {
+            const token = state.activeToken;
+            if (!token) {
+                return originalRequestAnimationFrame(callback);
+            }
+            increment(token);
+            let rafId = 0;
+            const wrapped = (timestamp) => {
+                const trackedToken = state.rafTokens.get(rafId) || token;
+                state.rafTokens.delete(rafId);
+                try {
+                    return withToken(trackedToken, () => callback(timestamp));
+                }
+                finally {
+                    decrement(trackedToken);
+                }
+            };
+            rafId = originalRequestAnimationFrame(wrapped);
+            state.rafTokens.set(rafId, token);
+            return rafId;
+        };
+        browserGlobal.cancelAnimationFrame = (rafId) => {
+            const token = state.rafTokens.get(rafId);
+            if (token) {
+                state.rafTokens.delete(rafId);
+                decrement(token);
+            }
+            return originalCancelAnimationFrame(rafId);
+        };
+    }
+    if (originalQueueMicrotask) {
+        browserGlobal.queueMicrotask = (callback) => {
+            const token = state.activeToken;
+            if (!token) {
+                return originalQueueMicrotask(callback);
+            }
+            increment(token);
+            return originalQueueMicrotask(() => {
+                try {
+                    return withToken(token, callback);
+                }
+                finally {
+                    decrement(token);
+                }
+            });
+        };
+    }
+    browserGlobal.__camofoxActionTracker = {
+        startAction(token) {
+            syncActiveToken(token);
+        },
+        finishAction(token) {
+            if (state.activeToken === token) {
+                syncActiveToken(0);
+            }
+        },
+        getPendingCount(token) {
+            return state.pendingCounts.get(token) || 0;
+        },
+        getActiveToken() {
+            return state.activeToken || 0;
+        },
+    };
+}
+async function ensureActionNavigationTracker(page) {
+    if (actionTrackerInstalledPages.has(page))
+        return true;
+    if (typeof page.addInitScript !== 'function' || typeof page.evaluate !== 'function')
+        return false;
+    try {
+        const context = page.context();
+        if (!actionTrackerBindingContexts.has(context) && typeof context.exposeBinding === 'function') {
+            await context.exposeBinding('__camofoxUpdateActiveToken', async ({ page: bindingPage }, token) => {
+                if (!bindingPage)
+                    return;
+                if (typeof token === 'number' && token > 0) {
+                    activeTrackedActionTokens.set(bindingPage, token);
+                }
+                else {
+                    activeTrackedActionTokens.delete(bindingPage);
+                }
+            });
+            await context.exposeBinding('__camofoxUpdatePendingCount', async ({ page: bindingPage }, token, count) => {
+                if (!bindingPage || typeof token !== 'number' || token <= 0)
+                    return;
+                const existing = trackedPendingCounts.get(bindingPage) || new Map();
+                if (typeof count === 'number' && count > 0) {
+                    existing.set(token, count);
+                    trackedPendingCounts.set(bindingPage, existing);
+                    return;
+                }
+                existing.delete(token);
+                if (existing.size === 0) {
+                    trackedPendingCounts.delete(bindingPage);
+                }
+                else {
+                    trackedPendingCounts.set(bindingPage, existing);
+                }
+            });
+            actionTrackerBindingContexts.add(context);
+        }
+        await page.addInitScript(installActionTrackerScript);
+        await page.evaluate(installActionTrackerScript);
+        actionTrackerInstalledPages.add(page);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function nextActionTrackerToken(page) {
+    const nextToken = (actionTrackerTokens.get(page) || 0) + 1;
+    actionTrackerTokens.set(page, nextToken);
+    return nextToken;
+}
+async function startTrackedAction(page) {
+    const trackerReady = await ensureActionNavigationTracker(page);
+    if (!trackerReady)
+        return null;
+    const token = nextActionTrackerToken(page);
+    await page.evaluate((trackedToken) => {
+        globalThis.__camofoxActionTracker?.startAction(trackedToken);
+    }, token);
+    activeTrackedActionTokens.set(page, token);
+    return token;
+}
+async function finishTrackedAction(page, token) {
+    if (token === null || typeof page.evaluate !== 'function')
+        return;
+    await page.evaluate((trackedToken) => {
+        globalThis.__camofoxActionTracker?.finishAction(trackedToken);
+    }, token).catch(() => { });
+    if (activeTrackedActionTokens.get(page) === token) {
+        activeTrackedActionTokens.delete(page);
+    }
+}
+async function getTrackedPendingCount(page, token) {
+    const syncedCount = trackedPendingCounts.get(page)?.get(token);
+    if (typeof syncedCount === 'number') {
+        return syncedCount;
+    }
+    if (typeof page.evaluate !== 'function')
+        return 0;
+    try {
+        return await page.evaluate((trackedToken) => {
+            return globalThis.__camofoxActionTracker?.getPendingCount(trackedToken) || 0;
+        }, token);
+    }
+    catch {
+        return 0;
+    }
+}
+async function getCurrentTrackedActionToken(page) {
+    if (typeof page.evaluate !== 'function' || !actionTrackerInstalledPages.has(page)) {
+        return activeTrackedActionTokens.get(page) || null;
+    }
+    try {
+        const token = await page.evaluate(() => {
+            return globalThis.__camofoxActionTracker?.getActiveToken?.() || 0;
+        });
+        if (typeof token === 'number' && token > 0) {
+            return token;
+        }
+        return activeTrackedActionTokens.get(page) || null;
+    }
+    catch {
+        return activeTrackedActionTokens.get(page) || null;
+    }
+}
+function incrementInFlightGuardCheck(page) {
+    inFlightGuardChecks.set(page, (inFlightGuardChecks.get(page) || 0) + 1);
+}
+function decrementInFlightGuardCheck(page) {
+    const next = (inFlightGuardChecks.get(page) || 0) - 1;
+    if (next > 0) {
+        inFlightGuardChecks.set(page, next);
+    }
+    else {
+        inFlightGuardChecks.delete(page);
+    }
+}
+function incrementTrackedInFlightGuardCheck(page, token) {
+    const existing = trackedInFlightGuardChecks.get(page) || new Map();
+    existing.set(token, (existing.get(token) || 0) + 1);
+    trackedInFlightGuardChecks.set(page, existing);
+}
+function decrementTrackedInFlightGuardCheck(page, token) {
+    const existing = trackedInFlightGuardChecks.get(page);
+    if (!existing)
+        return;
+    const next = (existing.get(token) || 0) - 1;
+    if (next > 0) {
+        existing.set(token, next);
+    }
+    else {
+        existing.delete(token);
+    }
+    if (existing.size === 0) {
+        trackedInFlightGuardChecks.delete(page);
+    }
+}
+function getTrackedInFlightGuardCheckCount(page, token) {
+    return trackedInFlightGuardChecks.get(page)?.get(token) || 0;
+}
+async function flushBlockedNavigationError(page) {
+    if (typeof page.waitForTimeout === 'function') {
+        await page.waitForTimeout(POST_ACTION_NAVIGATION_SETTLE_MS);
+    }
+    throwBlockedNavigationErrorIfPresent(page);
+}
+async function withBlockedNavigationTracking(page, action) {
+    if (CONFIG.allowPrivateNetworkTargets) {
+        return action();
+    }
+    clearBlockedNavigationError(page);
+    const actionToken = await startTrackedAction(page);
+    clearBlockedNavigationError(page);
+    let finishedTracking = false;
+    const finish = async () => {
+        if (finishedTracking)
+            return;
+        finishedTracking = true;
+        await finishTrackedAction(page, actionToken);
+    };
+    try {
+        const result = await action();
+        throwBlockedNavigationErrorIfPresent(page);
+        if (actionToken === null) {
+            await finish();
+            await flushBlockedNavigationError(page);
+            return result;
+        }
+        let sawPendingWork = false;
+        while (true) {
+            throwTrackedBlockedNavigationErrorIfPresent(page, actionToken);
+            if (sawPendingWork) {
+                throwBlockedNavigationErrorIfPresent(page);
+            }
+            const pendingCount = await getTrackedPendingCount(page, actionToken);
+            const inFlightGuardCount = getTrackedInFlightGuardCheckCount(page, actionToken);
+            if (pendingCount === 0 && inFlightGuardCount === 0) {
+                if (!sawPendingWork) {
+                    await new Promise((resolve) => setTimeout(resolve, ACTION_TRACKER_POLL_MS));
+                    throwTrackedBlockedNavigationErrorIfPresent(page, actionToken);
+                    throwBlockedNavigationErrorIfPresent(page);
+                    if ((await getTrackedPendingCount(page, actionToken)) === 0 && getTrackedInFlightGuardCheckCount(page, actionToken) === 0) {
+                        break;
+                    }
+                    sawPendingWork = true;
+                    continue;
+                }
+                await new Promise((resolve) => setTimeout(resolve, ACTION_TRACKER_POLL_MS));
+                throwTrackedBlockedNavigationErrorIfPresent(page, actionToken);
+                throwBlockedNavigationErrorIfPresent(page);
+                if ((await getTrackedPendingCount(page, actionToken)) === 0 && getTrackedInFlightGuardCheckCount(page, actionToken) === 0)
+                    break;
+            }
+            else {
+                sawPendingWork = true;
+                await new Promise((resolve) => setTimeout(resolve, ACTION_TRACKER_POLL_MS));
+            }
+        }
+        throwTrackedBlockedNavigationErrorIfPresent(page, actionToken);
+        if (sawPendingWork) {
+            throwBlockedNavigationErrorIfPresent(page);
+        }
+        await finish();
+        return result;
+    }
+    catch (err) {
+        await finish();
+        if (typeof err === 'object' && err !== null && 'statusCode' in err && typeof err.statusCode === 'number') {
+            throw err;
+        }
+        if (actionToken !== null) {
+            rethrowWithTrackedBlockedNavigationError(page, actionToken, err);
+        }
+        rethrowWithBlockedNavigationError(page, err);
+    }
+}
+function validateUrl(url, options = {}) {
+    const { allowPrivateNetworkTargets = CONFIG.allowPrivateNetworkTargets } = options;
     try {
         const parsed = new URL(url);
         if (!ALLOWED_URL_SCHEMES.includes(parsed.protocol)) {
             return `Blocked URL scheme: ${parsed.protocol} (only http/https allowed)`;
         }
+        if (!allowPrivateNetworkTargets && isBlockedPrivateNetworkHostname(parsed.hostname)) {
+            return `Blocked private network target: ${parsed.hostname}`;
+        }
         return null;
     }
     catch {
         return `Invalid URL: ${url}`;
     }
 }
+async function hostnameResolvesToBlockedAddress(hostname) {
+    const normalized = normalizeHostname(hostname);
+    if (isBlockedPrivateNetworkHostname(normalized))
+        return true;
+    try {
+        const results = await (0, promises_1.lookup)(normalized, { all: true, verbatim: true });
+        return results.some((result) => isBlockedPrivateNetworkHostname(result.address));
+    }
+    catch {
+        return false;
+    }
+}
+async function validateNavigationUrl(url, options = {}) {
+    const urlError = validateUrl(url, options);
+    if (urlError)
+        return urlError;
+    const { allowPrivateNetworkTargets = CONFIG.allowPrivateNetworkTargets } = options;
+    if (allowPrivateNetworkTargets)
+        return null;
+    const parsed = new URL(url);
+    if (await hostnameResolvesToBlockedAddress(parsed.hostname)) {
+        return `Blocked private network target: ${parsed.hostname}`;
+    }
+    return null;
+}
+async function navigateWithSafetyGuard(page, targetUrl, options = {}) {
+    const { allowPrivateNetworkTargets = CONFIG.allowPrivateNetworkTargets, waitUntil = 'domcontentloaded', timeout = 30000 } = options;
+    const initialError = await validateNavigationUrl(targetUrl, { allowPrivateNetworkTargets });
+    if (initialError) {
+        throw createNavigationBlockError(initialError);
+    }
+    if (allowPrivateNetworkTargets) {
+        await page.goto(targetUrl, { waitUntil, timeout });
+        return;
+    }
+    const typedPage = page;
+    await ensureNavigationSafetyGuard(typedPage, { allowPrivateNetworkTargets });
+    blockedNavigationErrors.delete(typedPage);
+    try {
+        await page.goto(targetUrl, { waitUntil, timeout });
+    }
+    catch (err) {
+        rethrowWithBlockedNavigationError(typedPage, err);
+    }
+}
 function annotateAriaYamlWithRefs(ariaYaml, refs) {
     let annotatedYaml = ariaYaml || '';
     if (!annotatedYaml || !refs || refs.size === 0)
@@ -200,40 +809,48 @@ function annotateAriaYamlWithRefs(ariaYaml, refs) {
 async function waitForPageReady(page, options = {}) {
     const { timeout = 10000, waitForNetwork = true } = options;
     try {
-        await page.waitForLoadState('domcontentloaded', { timeout });
-        if (waitForNetwork) {
-            await page.waitForLoadState('networkidle', { timeout: 5000 }).catch(() => {
-                (0, logging_1.log)('warn', 'networkidle timeout, continuing');
-            });
-        }
-        // Framework hydration wait (React/Next.js/Vue) - mirrors Swift WebView.swift logic
-        // Wait for readyState === 'complete' + network quiet (40 iterations × 250ms max)
-        await page
-            .evaluate(async () => {
-            const perf = globalThis.performance;
-            const doc = globalThis.document;
-            const raf = globalThis.requestAnimationFrame;
-            for (let i = 0; i < 40; i++) {
-                // Check if network is quiet (no recent resource loads)
-                const entries = perf.getEntriesByType('resource');
-                const recentEntries = entries.slice(-5);
-                const netQuiet = recentEntries.every((e) => (perf.now() - e.responseEnd) > 400);
-                if (doc.readyState === 'complete' && netQuiet) {
-                    // Double RAF to ensure paint is complete
-                    await new Promise((r) => raf(() => raf(() => r())));
-                    break;
-                }
-                await new Promise((r) => setTimeout(r, 250));
+        await withBlockedNavigationTracking(page, async () => {
+            await page.waitForLoadState('domcontentloaded', { timeout });
+            if (waitForNetwork) {
+                await page.waitForLoadState('networkidle', { timeout: 5000 }).catch(() => {
+                    (0, logging_1.log)('warn', 'networkidle timeout, continuing');
+                });
             }
-        })
-            .catch(() => {
-            (0, logging_1.log)('warn', 'hydration wait failed, continuing');
+            // Framework hydration wait (React/Next.js/Vue) - mirrors Swift WebView.swift logic
+            // Wait for readyState === 'complete' + network quiet (40 iterations × 250ms max)
+            await page
+                .evaluate(async () => {
+                const perf = globalThis.performance;
+                const doc = globalThis.document;
+                const raf = globalThis.requestAnimationFrame;
+                for (let i = 0; i < 40; i++) {
+                    // Check if network is quiet (no recent resource loads)
+                    const entries = perf.getEntriesByType('resource');
+                    const recentEntries = entries.slice(-5);
+                    const netQuiet = recentEntries.every((e) => (perf.now() - e.responseEnd) > 400);
+                    if (doc.readyState === 'complete' && netQuiet) {
+                        // Double RAF to ensure paint is complete
+                        await new Promise((r) => raf(() => raf(() => r())));
+                        break;
+                    }
+                    await new Promise((r) => setTimeout(r, 250));
+                }
+            })
+                .catch(() => {
+                (0, logging_1.log)('warn', 'hydration wait failed, continuing');
+            });
+            await page.waitForTimeout(200);
+            await dismissConsentDialogs(page);
         });
-        await page.waitForTimeout(200);
-        await dismissConsentDialogs(page);
         return true;
     }
     catch (err) {
+        if (typeof err === 'object' && err !== null && 'statusCode' in err && typeof err.statusCode === 'number') {
+            throw err;
+        }
+        const blockedError = takeBlockedNavigationError(page);
+        if (blockedError)
+            throw blockedError;
         const message = err instanceof Error ? err.message : String(err);
         (0, logging_1.log)('warn', 'page ready failed', { error: message });
         return false;
@@ -409,7 +1026,76 @@ function attachConsoleListeners(state) {
         }
     });
 }
-function createTabState(page) {
+async function ensureNavigationSafetyGuard(page, options = {}) {
+    const { allowPrivateNetworkTargets = CONFIG.allowPrivateNetworkTargets } = options;
+    if (allowPrivateNetworkTargets)
+        return;
+    const context = page.context();
+    if (navigationGuardHandlers.has(context))
+        return;
+    const routeHandler = async (route) => {
+        const request = route.request();
+        if (typeof request.isNavigationRequest === 'function' && !request.isNavigationRequest()) {
+            return route.continue();
+        }
+        const requestFrame = typeof request.frame === 'function' ? request.frame() : null;
+        const requestPage = requestFrame && typeof requestFrame.page === 'function' ? requestFrame.page() : null;
+        const relatedPages = new Set();
+        let trackedToken = null;
+        if (requestPage) {
+            relatedPages.add(requestPage);
+            trackedToken = await getCurrentTrackedActionToken(requestPage);
+            const mappedOpener = popupOpenerPages.get(requestPage);
+            if (mappedOpener) {
+                relatedPages.add(mappedOpener);
+                if (trackedToken === null) {
+                    trackedToken = await getCurrentTrackedActionToken(mappedOpener);
+                }
+            }
+            else if (typeof requestPage.opener === 'function') {
+                const openerPage = await requestPage.opener().catch(() => null);
+                if (openerPage) {
+                    relatedPages.add(openerPage);
+                    if (trackedToken === null) {
+                        trackedToken = await getCurrentTrackedActionToken(openerPage);
+                    }
+                }
+            }
+        }
+        for (const relatedPage of relatedPages) {
+            incrementInFlightGuardCheck(relatedPage);
+            if (trackedToken !== null) {
+                incrementTrackedInFlightGuardCheck(relatedPage, trackedToken);
+            }
+        }
+        try {
+            const requestError = await validateNavigationUrl(request.url(), { allowPrivateNetworkTargets: false });
+            if (requestError) {
+                for (const relatedPage of relatedPages) {
+                    if (trackedToken !== null) {
+                        setTrackedBlockedNavigationError(relatedPage, trackedToken, requestError);
+                    }
+                    else {
+                        blockedNavigationErrors.set(relatedPage, requestError);
+                    }
+                }
+                return route.abort('blockedbyclient');
+            }
+            return route.continue();
+        }
+        finally {
+            for (const relatedPage of relatedPages) {
+                decrementInFlightGuardCheck(relatedPage);
+                if (trackedToken !== null) {
+                    decrementTrackedInFlightGuardCheck(relatedPage, trackedToken);
+                }
+            }
+        }
+    };
+    await context.route('**/*', routeHandler);
+    navigationGuardHandlers.set(context, routeHandler);
+}
+async function createTabState(page) {
     const state = {
         page,
         refs: new Map(),
@@ -419,6 +1105,10 @@ function createTabState(page) {
         pageErrors: [],
     };
     attachConsoleListeners(state);
+    page.on('popup', (popupPage) => {
+        popupOpenerPages.set(popupPage, page);
+    });
+    await ensureNavigationSafetyGuard(page, { allowPrivateNetworkTargets: CONFIG.allowPrivateNetworkTargets });
     return state;
 }
 async function navigateTab(tabId, tabState, params) {
@@ -430,7 +1120,7 @@ async function navigateTab(tabId, tabState, params) {
     if (!targetUrl) {
         throw new Error('url or macro required');
     }
-    const urlErr = validateUrl(targetUrl);
+    const urlErr = await validateNavigationUrl(targetUrl, { allowPrivateNetworkTargets: params.allowPrivateNetworkTargets });
     if (urlErr) {
         const err = new Error(urlErr);
         // Used by routes to map to 400.
@@ -438,7 +1128,11 @@ async function navigateTab(tabId, tabState, params) {
         throw err;
     }
     return withTabLock(tabId, async () => {
-        await tabState.page.goto(targetUrl, { waitUntil: 'domcontentloaded', timeout: 30000 });
+        await navigateWithSafetyGuard(tabState.page, targetUrl, {
+            allowPrivateNetworkTargets: params.allowPrivateNetworkTargets,
+            waitUntil: 'domcontentloaded',
+            timeout: 30000,
+        });
         tabState.visitedUrls.add(targetUrl);
         tabState.refs = await buildRefs(tabState.page);
         return { ok: true, url: tabState.page.url() };
@@ -454,6 +1148,19 @@ async function snapshotTab(tabState) {
         refsCount: tabState.refs.size,
     };
 }
+function buildSnapshotPayload(raw, offset = 0) {
+    const windowed = (0, snapshot_1.windowSnapshot)(raw.snapshot, offset, CONFIG.maxSnapshotChars, CONFIG.snapshotTailChars);
+    return {
+        url: raw.url,
+        snapshot: windowed.text,
+        refsCount: raw.refsCount,
+        offset: windowed.offset,
+        truncated: windowed.truncated,
+        totalChars: windowed.totalChars,
+        hasMore: windowed.hasMore ?? false,
+        nextOffset: windowed.nextOffset ?? null,
+    };
+}
 async function clickTab(tabId, tabState, params) {
     const { ref, selector } = params;
     if (!ref && !selector) {
@@ -462,61 +1169,69 @@ async function clickTab(tabId, tabState, params) {
         throw err;
     }
     return withTabLock(tabId, async () => {
-        const dispatchMouseSequence = async (locator) => {
-            const box = await locator.boundingBox();
-            if (!box)
-                throw new Error('Element not visible (no bounding box)');
-            const x = box.x + box.width / 2;
-            const y = box.y + box.height / 2;
-            await tabState.page.mouse.move(x, y);
-            await tabState.page.waitForTimeout(50);
-            await tabState.page.mouse.down();
-            await tabState.page.waitForTimeout(50);
-            await tabState.page.mouse.up();
-            (0, logging_1.log)('info', 'mouse sequence dispatched', { x: x.toFixed(0), y: y.toFixed(0) });
-        };
-        const doClick = async (locatorOrSelector, isLocator) => {
-            const locator = isLocator ? locatorOrSelector : tabState.page.locator(locatorOrSelector);
-            try {
-                await locator.click({ timeout: 5000 });
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                if (message.includes('intercepts pointer events')) {
-                    (0, logging_1.log)('warn', 'click intercepted, retrying with force');
-                    try {
-                        await locator.click({ timeout: 5000, force: true });
+        try {
+            const dispatchMouseSequence = async (locator) => {
+                const box = await locator.boundingBox();
+                if (!box)
+                    throw new Error('Element not visible (no bounding box)');
+                const x = box.x + box.width / 2;
+                const y = box.y + box.height / 2;
+                await tabState.page.mouse.move(x, y);
+                await tabState.page.waitForTimeout(50);
+                await tabState.page.mouse.down();
+                await tabState.page.waitForTimeout(50);
+                await tabState.page.mouse.up();
+                (0, logging_1.log)('info', 'mouse sequence dispatched', { x: x.toFixed(0), y: y.toFixed(0) });
+            };
+            const doClick = async (locatorOrSelector, isLocator) => {
+                const locator = isLocator ? locatorOrSelector : tabState.page.locator(locatorOrSelector);
+                try {
+                    await locator.click({ timeout: 5000 });
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    if (message.includes('intercepts pointer events')) {
+                        (0, logging_1.log)('warn', 'click intercepted, retrying with force');
+                        try {
+                            await locator.click({ timeout: 5000, force: true });
+                        }
+                        catch {
+                            (0, logging_1.log)('warn', 'force click failed, trying mouse sequence');
+                            await dispatchMouseSequence(locator);
+                        }
                     }
-                    catch {
-                        (0, logging_1.log)('warn', 'force click failed, trying mouse sequence');
+                    else if (message.includes('not visible') || message.includes('timeout')) {
+                        (0, logging_1.log)('warn', 'click timeout, trying mouse sequence');
                         await dispatchMouseSequence(locator);
                     }
+                    else {
+                        throw err;
+                    }
                 }
-                else if (message.includes('not visible') || message.includes('timeout')) {
-                    (0, logging_1.log)('warn', 'click timeout, trying mouse sequence');
-                    await dispatchMouseSequence(locator);
+            };
+            await withBlockedNavigationTracking(tabState.page, async () => {
+                if (ref) {
+                    const locator = await refToLocator(tabState.page, ref, tabState.refs);
+                    if (!locator) {
+                        const maxRef = tabState.refs.size > 0 ? `e${tabState.refs.size}` : 'none';
+                        const err = new Error(`Unknown ref: ${ref} (valid refs: e1-${maxRef}, ${tabState.refs.size} total). Refs reset after navigation - call snapshot first.`);
+                        err.statusCode = 400;
+                        throw err;
+                    }
+                    await doClick(locator, true);
                 }
                 else {
-                    throw err;
+                    await doClick(selector, false);
                 }
-            }
-        };
-        if (ref) {
-            const locator = await refToLocator(tabState.page, ref, tabState.refs);
-            if (!locator) {
-                const maxRef = tabState.refs.size > 0 ? `e${tabState.refs.size}` : 'none';
-                throw new Error(`Unknown ref: ${ref} (valid refs: e1-${maxRef}, ${tabState.refs.size} total). Refs reset after navigation - call snapshot first.`);
-            }
-            await doClick(locator, true);
+            });
+            tabState.refs = await buildRefs(tabState.page);
+            const newUrl = tabState.page.url();
+            tabState.visitedUrls.add(newUrl);
+            return { ok: true, url: newUrl };
         }
-        else {
-            await doClick(selector, false);
+        catch (err) {
+            rethrowWithBlockedNavigationError(tabState.page, err);
         }
-        await tabState.page.waitForTimeout(500);
-        tabState.refs = await buildRefs(tabState.page);
-        const newUrl = tabState.page.url();
-        tabState.visitedUrls.add(newUrl);
-        return { ok: true, url: newUrl };
     });
 }
 /**
@@ -607,28 +1322,43 @@ async function typeTab(tabId, tabState, params) {
         let locator;
         if (ref) {
             const resolved = await refToLocator(tabState.page, ref, tabState.refs);
-            if (!resolved)
-                throw new Error(`Unknown ref: ${ref}`);
+            if (!resolved) {
+                const err = new Error(`Unknown ref: ${ref}. Call snapshot first.`);
+                err.statusCode = 400;
+                throw err;
+            }
             locator = resolved;
         }
         else {
             locator = tabState.page.locator(selector);
         }
-        await smartFill(locator, tabState.page, text);
+        await withBlockedNavigationTracking(tabState.page, async () => {
+            await smartFill(locator, tabState.page, text);
+        });
     });
     return { ok: true };
 }
 async function pressTab(tabId, tabState, key) {
     await withTabLock(tabId, async () => {
-        await tabState.page.keyboard.press(key);
+        try {
+            await withBlockedNavigationTracking(tabState.page, async () => {
+                await tabState.page.keyboard.press(key);
+            });
+        }
+        catch (err) {
+            rethrowWithBlockedNavigationError(tabState.page, err);
+        }
     });
     return { ok: true };
 }
 async function scrollTab(tabState, params) {
     const { direction = 'down', amount = 500 } = params;
-    const delta = direction === 'up' ? -amount : amount;
-    await tabState.page.mouse.wheel(0, delta);
-    await tabState.page.waitForTimeout(300);
+    const isHorizontal = direction === 'left' || direction === 'right';
+    const delta = direction === 'up' || direction === 'left' ? -amount : amount;
+    await withBlockedNavigationTracking(tabState.page, async () => {
+        await tabState.page.mouse.wheel(isHorizontal ? delta : 0, isHorizontal ? 0 : delta);
+        await tabState.page.waitForTimeout(300);
+    });
     return { ok: true };
 }
 async function scrollElementTab(tabId, tabState, params) {
@@ -661,28 +1391,30 @@ async function scrollElementTab(tabId, tabState, params) {
             }
         }
         const element = locator.first();
-        if (scrollTo) {
-            await element.evaluate((el, pos) => {
-                const e = el;
-                const p = pos;
-                if (p.top !== undefined)
-                    e.scrollTop = p.top;
-                if (p.left !== undefined)
-                    e.scrollLeft = p.left;
-            }, scrollTo);
-        }
-        else {
-            const deltaX = params.deltaX ?? 0;
-            const deltaY = params.deltaY ?? 300;
-            await element.evaluate((el, delta) => {
-                el.scrollBy({
-                    top: delta.y,
-                    left: delta.x,
-                    behavior: 'auto',
-                });
-            }, { x: deltaX, y: deltaY });
-        }
-        await page.waitForTimeout(200);
+        await withBlockedNavigationTracking(page, async () => {
+            if (scrollTo) {
+                await element.evaluate((el, pos) => {
+                    const e = el;
+                    const p = pos;
+                    if (p.top !== undefined)
+                        e.scrollTop = p.top;
+                    if (p.left !== undefined)
+                        e.scrollLeft = p.left;
+                }, scrollTo);
+            }
+            else {
+                const deltaX = params.deltaX ?? 0;
+                const deltaY = params.deltaY ?? 300;
+                await element.evaluate((el, delta) => {
+                    el.scrollBy({
+                        top: delta.y,
+                        left: delta.x,
+                        behavior: 'auto',
+                    });
+                }, { x: deltaX, y: deltaY });
+            }
+            await page.waitForTimeout(200);
+        });
         const scrollPosition = (await element.evaluate((el) => {
             const e = el;
             return {
@@ -712,7 +1444,9 @@ async function _evaluateInternal(tabId, tabState, params, config) {
             timeoutId = setTimeout(() => reject(new Error('EVAL_TIMEOUT')), timeout);
         });
         try {
-            const result = await Promise.race([page.evaluate(params.expression), timeoutPromise]);
+            const result = await withBlockedNavigationTracking(page, async () => {
+                return Promise.race([page.evaluate(params.expression), timeoutPromise]);
+            });
             const serialized = JSON.stringify(result);
             if (serialized === undefined) {
                 return {
@@ -739,7 +1473,11 @@ async function _evaluateInternal(tabId, tabState, params, config) {
             };
         }
         catch (err) {
+            if (typeof err === 'object' && err !== null && 'statusCode' in err && typeof err.statusCode === 'number') {
+                throw err;
+            }
             const message = err instanceof Error ? err.message : String(err);
+            throwBlockedNavigationErrorIfPresent(page);
             if (message === 'EVAL_TIMEOUT') {
                 return {
                     ok: false,
@@ -767,23 +1505,38 @@ async function evaluateTabExtended(tabId, tabState, params) {
 }
 async function backTab(tabId, tabState) {
     return withTabLock(tabId, async () => {
-        await tabState.page.goBack({ timeout: 10000 });
-        tabState.refs = await buildRefs(tabState.page);
-        return { ok: true, url: tabState.page.url() };
+        try {
+            await tabState.page.goBack({ timeout: 10000 });
+            tabState.refs = await buildRefs(tabState.page);
+            return { ok: true, url: tabState.page.url() };
+        }
+        catch (err) {
+            rethrowWithBlockedNavigationError(tabState.page, err);
+        }
     });
 }
 async function forwardTab(tabId, tabState) {
     return withTabLock(tabId, async () => {
-        await tabState.page.goForward({ timeout: 10000 });
-        tabState.refs = await buildRefs(tabState.page);
-        return { ok: true, url: tabState.page.url() };
+        try {
+            await tabState.page.goForward({ timeout: 10000 });
+            tabState.refs = await buildRefs(tabState.page);
+            return { ok: true, url: tabState.page.url() };
+        }
+        catch (err) {
+            rethrowWithBlockedNavigationError(tabState.page, err);
+        }
     });
 }
 async function refreshTab(tabId, tabState) {
     return withTabLock(tabId, async () => {
-        await tabState.page.reload({ timeout: 30000 });
-        tabState.refs = await buildRefs(tabState.page);
-        return { ok: true, url: tabState.page.url() };
+        try {
+            await tabState.page.reload({ timeout: 30000 });
+            tabState.refs = await buildRefs(tabState.page);
+            return { ok: true, url: tabState.page.url() };
+        }
+        catch (err) {
+            rethrowWithBlockedNavigationError(tabState.page, err);
+        }
     });
 }
 async function getLinks(tabState, params) {