agentic-stealth-browser 2.5.0__tar.gz → 2.6.0__tar.gz

{agentic_stealth_browser-2.5.0 → agentic_stealth_browser-2.6.0}/CHANGELOG.md

@@ -9,6 +9,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.6.0] — Stealth & MCP Hardening (2026-07-12)
+
+### Added
+- **`attach_mode` param** (`stealth/advanced_stealth.py`): `get_stealth_script(..., attach_mode=True)` skips `navigator.platform` / WebGL vendor-renderer / screen-DPR overrides when attaching to a real browser, so the injected fingerprint no longer contradicts the real OS/GPU. `core/agent_browser.py`'s `attach_over_cdp()` now passes `attach_mode=True`.
+- **`AdapterToolError`** (`production/adapters/`): raised when an MCP tool result carries `isError: true` — previously a failed `navigate`/`click`/`fill` call reported silent success.
+- **Canonical `connected` field** on adapter `status()` (`production/adapters/`), with a `running` back-compat alias.
+- **CDP bridge profile resolution** (`production/adapters/cdp_bridge.py`): `launch(profile)` now accepts either a raw `ws/wss/http(s)` endpoint or a profile name resolved via `CDP_ENDPOINT_<PROFILE>` / `CDP_ENDPOINT` env, aligning its signature with the `BackendAdapter` protocol and sibling adapters.
+- Adapter, stealth, and recovery unit tests covering the above (`tests/test_adapter_*.py`, `tests/test_stealth_modules.py`, `tests/test_recovery_state_machine.py`).
+- `CLAUDE.md`: contributor guidance (setup, test commands mirroring CI, architecture map, conventions).
+
+### Fixed
+- **Per-patch isolation** (`stealth/advanced_stealth.py`): each stealth patch now runs in its own try/catch, so one API mismatch no longer aborts every patch queued after it.
+- **Rotation failure correctness** (`recovery/anti_block_orchestrator.py`): a failed `ROTATE_*` action now returns `False` and records `_update_recovery_history(success=False)` instead of silently succeeding; per-attempt session/proxy names get a uuid suffix to avoid collisions; a redundant tentative history update was removed.
+- **playwright-mcp pin** (`production/adapters/playwright_mcp.py`): pinned to `@playwright/mcp@0.0.78` with corrected `browser_navigate`/`browser_click`/`browser_type` schema (`element`/`target`/`text`).
+
+### Security
+- **WebRTC leak fix** (`stealth/advanced_stealth.py`): `onicecandidate` is now rebound per-instance instead of on the shared prototype (no cross-instance/global leak); `addEventListener('icecandidate', ...)` listeners are now filtered too; `createDataChannel` restored to a real passthrough.
+- **PolicyEngine + ApprovalGate wiring** (`production/mcp_server.py`): both now sit in the `tools/call` dispatch path and workflow replay. Fail-open by default — no policy files means allow-all and auto-approve, so existing flows are unchanged — operators opt into enforcement via `STEALTH_MCP_POLICY` env or an approval callback.
+- **Honesty docstring** (`production/mcp_session_isolation.py`): documents that `SessionEnforcer` is defined and tested but NOT wired into the dispatch path — inert until a multi-client transport exists (single-client stdio has no per-context token).
+
+### Changed
+- `core/agent_browser.py`: `attach_over_cdp()` passes `attach_mode=True` through to the stealth script generator (see Added).
+
+---
+
 ## [2.5.0] — Real Dashboard Backend Adapters (#444) (2026-06-07)
 
 ### Added
@@ -405,7 +430,8 @@ See the full v0.9.0 milestone and the stacked PRs #383/#384/#385 for implementat
 
 ---
 
-[unreleased]: https://github.com/shanewas/agentic-stealth-browser/compare/v2.3.0...HEAD
+[unreleased]: https://github.com/shanewas/agentic-stealth-browser/compare/v2.6.0...HEAD
+[2.6.0]: https://github.com/shanewas/agentic-stealth-browser/releases/tag/v2.6.0
 [2.3.0]: https://github.com/shanewas/agentic-stealth-browser/releases/tag/v2.3.0
 [2.1.1]: https://github.com/shanewas/agentic-stealth-browser/releases/tag/v2.1.1
 [2.1.0]: https://github.com/shanewas/agentic-stealth-browser/releases/tag/v2.1.0

{agentic_stealth_browser-2.5.0 → agentic_stealth_browser-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-stealth-browser
-Version: 2.5.0
+Version: 2.6.0
 Summary: Production-grade, human-mimicking browser automation framework for autonomous agents. Survives modern anti-bot systems.
 Author-email: Shane W <shanewas@users.noreply.github.com>
 License-Expression: MIT
@@ -224,6 +224,29 @@ live E2E (`RUN_E2E_ANTI_BLOCK=1` to enable).
 
 ---
 
+## New in v2.6.0
+
+- **Stealth patch isolation** — per-patch try/catch in `advanced_stealth.py`; one
+  API mismatch no longer aborts every patch queued after it
+- **Attach-mode fingerprint coherence** — new `attach_mode` skips
+  navigator.platform / WebGL vendor-renderer / screen-DPR overrides that would
+  otherwise contradict a real attached browser's OS/GPU
+- **WebRTC leak hardening** — per-instance `onicecandidate` rebind (no
+  prototype-global leak); the `addEventListener('icecandidate')` variant is
+  now filtered too
+- **MCP policy/approval gates** — `PolicyEngine` + `ApprovalGate` wired into
+  the dispatch path, fail-open by default (opt-in enforcement via
+  `STEALTH_MCP_POLICY` env)
+- **Adapter `isError` surfacing** — failed MCP tool calls now raise
+  `AdapterToolError` instead of reporting silent success; playwright-mcp
+  pinned to 0.0.78 with the corrected tool schema
+- **Recovery rotation-failure correctness** — failed rotations now propagate
+  and record history instead of silently succeeding
+
+See [CHANGELOG.md](CHANGELOG.md) for the full release history.
+
+---
+
 ## New in v2.5.0
 
 - **BackendAdapter protocol** — pluggable execution backends (M0–M4 shipped)

{agentic_stealth_browser-2.5.0 → agentic_stealth_browser-2.6.0}/README.md

@@ -185,6 +185,29 @@ live E2E (`RUN_E2E_ANTI_BLOCK=1` to enable).
 
 ---
 
+## New in v2.6.0
+
+- **Stealth patch isolation** — per-patch try/catch in `advanced_stealth.py`; one
+  API mismatch no longer aborts every patch queued after it
+- **Attach-mode fingerprint coherence** — new `attach_mode` skips
+  navigator.platform / WebGL vendor-renderer / screen-DPR overrides that would
+  otherwise contradict a real attached browser's OS/GPU
+- **WebRTC leak hardening** — per-instance `onicecandidate` rebind (no
+  prototype-global leak); the `addEventListener('icecandidate')` variant is
+  now filtered too
+- **MCP policy/approval gates** — `PolicyEngine` + `ApprovalGate` wired into
+  the dispatch path, fail-open by default (opt-in enforcement via
+  `STEALTH_MCP_POLICY` env)
+- **Adapter `isError` surfacing** — failed MCP tool calls now raise
+  `AdapterToolError` instead of reporting silent success; playwright-mcp
+  pinned to 0.0.78 with the corrected tool schema
+- **Recovery rotation-failure correctness** — failed rotations now propagate
+  and record history instead of silently succeeding
+
+See [CHANGELOG.md](CHANGELOG.md) for the full release history.
+
+---
+
 ## New in v2.5.0
 
 - **BackendAdapter protocol** — pluggable execution backends (M0–M4 shipped)

{agentic_stealth_browser-2.5.0 → agentic_stealth_browser-2.6.0}/agentic_stealth_browser.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-stealth-browser
-Version: 2.5.0
+Version: 2.6.0
 Summary: Production-grade, human-mimicking browser automation framework for autonomous agents. Survives modern anti-bot systems.
 Author-email: Shane W <shanewas@users.noreply.github.com>
 License-Expression: MIT
@@ -224,6 +224,29 @@ live E2E (`RUN_E2E_ANTI_BLOCK=1` to enable).
 
 ---
 
+## New in v2.6.0
+
+- **Stealth patch isolation** — per-patch try/catch in `advanced_stealth.py`; one
+  API mismatch no longer aborts every patch queued after it
+- **Attach-mode fingerprint coherence** — new `attach_mode` skips
+  navigator.platform / WebGL vendor-renderer / screen-DPR overrides that would
+  otherwise contradict a real attached browser's OS/GPU
+- **WebRTC leak hardening** — per-instance `onicecandidate` rebind (no
+  prototype-global leak); the `addEventListener('icecandidate')` variant is
+  now filtered too
+- **MCP policy/approval gates** — `PolicyEngine` + `ApprovalGate` wired into
+  the dispatch path, fail-open by default (opt-in enforcement via
+  `STEALTH_MCP_POLICY` env)
+- **Adapter `isError` surfacing** — failed MCP tool calls now raise
+  `AdapterToolError` instead of reporting silent success; playwright-mcp
+  pinned to 0.0.78 with the corrected tool schema
+- **Recovery rotation-failure correctness** — failed rotations now propagate
+  and record history instead of silently succeeding
+
+See [CHANGELOG.md](CHANGELOG.md) for the full release history.
+
+---
+
 ## New in v2.5.0
 
 - **BackendAdapter protocol** — pluggable execution backends (M0–M4 shipped)

{agentic_stealth_browser-2.5.0 → agentic_stealth_browser-2.6.0}/agentic_stealth_browser.egg-info/SOURCES.txt

@@ -182,6 +182,9 @@ tests/test_workflow_orchestrator.py
 tests/test_workflow_schema.py
 tests/test_workflow_schema_unit.py
 tests/test_workflow_versioning.py
+tests/stealth_harness/__init__.py
+tests/stealth_harness/collect.py
+tests/stealth_harness/test_stealth.py
 workflows/__init__.py
 workflows/action_interpreter.py
 workflows/player.py

{agentic_stealth_browser-2.5.0 → agentic_stealth_browser-2.6.0}/core/agent_browser.py

@@ -2274,7 +2274,9 @@ class AgentBrowser:
             if apply_stealth:
                 session_name = (self.session or {}).get("name", "default-session")
                 fp_seed = f"agentic-{session_name}-canvas-v4"
-                stealth_script = get_stealth_script(fingerprint_seed=fp_seed)
+                stealth_script = get_stealth_script(
+                    fingerprint_seed=fp_seed, attach_mode=True
+                )
                 try:
                     await ctx.add_init_script(stealth_script)
                     stealth_installed = True

{agentic_stealth_browser-2.5.0 → agentic_stealth_browser-2.6.0}/production/adapters/__init__.py

@@ -9,6 +9,7 @@ Public surface:
     Capability             - the feature enum
     AdapterLaunchError     - cannot start (runtime)
     AdapterCapabilityError - cannot perform a requested action
+    AdapterToolError       - MCP tool call reported isError: true
     AdapterNotFoundError   - get_adapter() was called with an unknown name
     BACKEND_REGISTRY       - mutable dict[name -> Adapter class]
     get_adapter(name)      - registry lookup with friendly error
@@ -21,6 +22,7 @@ from production.adapters.base import (
     AdapterCapabilityError,
     AdapterLaunchError,
     AdapterNotFoundError,
+    AdapterToolError,
     BackendAdapter,
     Capability,
 )
@@ -103,6 +105,7 @@ __all__ = [
     "AdapterCapabilityError",
     "AdapterLaunchError",
     "AdapterNotFoundError",
+    "AdapterToolError",
     "BACKEND_REGISTRY",
     "BackendAdapter",
     "Capability",

{agentic_stealth_browser-2.5.0 → agentic_stealth_browser-2.6.0}/production/adapters/agentic_stealth_mcp.py

@@ -24,6 +24,7 @@ from production.adapters._jsonrpc_stdio import JsonRpcStdioClient
 from production.adapters.base import (
     AdapterCapabilityError,
     AdapterLaunchError,
+    AdapterToolError,
     Capability,
 )
 
@@ -118,7 +119,7 @@ class AgenticStealthMCPAdapter:
                     "protocolVersion": "2024-11-05",
                     "clientInfo": {
                         "name": "agentic-stealth-browser-dashboard",
-                        "version": "2.5.0",
+                        "version": "2.6.0",
                     },
                     "capabilities": {},
                 },
@@ -199,9 +200,11 @@ class AgenticStealthMCPAdapter:
         return str(path)
 
     async def status(self) -> dict[str, Any]:
+        alive = self._proc is not None and self._proc.returncode is None
         return {
             "backend": self.name,
-            "running": self._proc is not None and self._proc.returncode is None,
+            "connected": alive,
+            "running": alive,  # back-compat alias; "connected" is canonical
             "headless": self._headless,
             "profile": self._profile,
         }
@@ -215,7 +218,12 @@ class AgenticStealthMCPAdapter:
         response = await self._client.request(
             "tools/call", {"name": name, "arguments": arguments}
         )
-        return response.get("result", {})
+        result = response.get("result", {})
+        if result.get("isError"):
+            raise AdapterToolError(
+                f"MCP tool {name!r} failed: {result.get('content')!r}"
+            )
+        return result
 
     def _require_capability(self, cap: Capability) -> None:
         """Raise AdapterCapabilityError when the active adapter does not

{agentic_stealth_browser-2.5.0 → agentic_stealth_browser-2.6.0}/production/adapters/base.py

@@ -46,6 +46,20 @@ class AdapterCapabilityError(RuntimeError):
     """
 
 
+class AdapterToolError(RuntimeError):
+    """Raised when an MCP tool call completes as a valid JSON-RPC response
+    but reports a tool-level failure (``result["isError"] is True``).
+
+    MCP servers report a failed tool execution (bad selector, navigation
+    timeout, etc.) as a *successful* JSON-RPC call whose result carries
+    ``isError: true`` — not as a JSON-RPC protocol-level error. Without this
+    exception, adapters would silently treat a failed navigate/click/fill/
+    screenshot as success. Distinct from AdapterLaunchError (process/handshake
+    failures) and the plain RuntimeError raised by JsonRpcStdioClient for
+    JSON-RPC protocol errors (e.g. unknown method).
+    """
+
+
 class AdapterNotFoundError(LookupError):
     """Raised by get_adapter() when the requested name is not in
     BACKEND_REGISTRY. Inherits from LookupError (the natural superclass for

{agentic_stealth_browser-2.5.0 → agentic_stealth_browser-2.6.0}/production/adapters/cdp_bridge.py

@@ -14,6 +14,7 @@ running and reachable at the CDP endpoint.
 
 from __future__ import annotations
 
+import os
 from typing import Any, Optional
 
 from playwright.async_api import (
@@ -72,17 +73,24 @@ class CDPBridgeAdapter:
         return capability in self.capabilities()
 
     # ------------------------------------------------------------------ launch
-    async def launch(self, endpoint: str, headless: bool = True) -> None:
+    async def launch(self, profile: str, headless: bool = True) -> None:
         """Connect to an existing CDP endpoint. Does NOT spawn a new browser.
 
         Args:
-            endpoint: ws:// or wss:// URL of the Chrome DevTools Protocol server.
+            profile: either a raw ws:// / wss:// / http(s):// CDP endpoint URL
+                (back-compat with direct callers of this adapter), or a
+                profile name — consistent with the base.py contract and the
+                M2/M3 adapters — resolved to an endpoint via the
+                ``CDP_ENDPOINT_<PROFILE>`` (or generic ``CDP_ENDPOINT``)
+                environment variable.
             headless: cosmetic flag, passed to spec but the remote browser's
                       display state is determined by its own launch args.
 
         Raises:
-            AdapterLaunchError: if the connection cannot be established.
+            AdapterLaunchError: if the connection cannot be established, or
+                (for a profile name) if no endpoint is configured for it.
         """
+        endpoint = self._resolve_endpoint(profile)
         self._endpoint = endpoint
         self._playwright = await async_playwright().start()
         try:
@@ -103,6 +111,23 @@ class CDPBridgeAdapter:
         self._context = await self._browser.new_context()
         self._owns_page = True
 
+    # ponytail: profile -> endpoint resolution is a flat env-var lookup, not
+    # a real profile registry. Fine while operators set one CDP target per
+    # profile by hand; upgrade to a config-file-backed mapping if/when the
+    # dashboard needs to drive many named CDP profiles at once.
+    @staticmethod
+    def _resolve_endpoint(profile: str) -> str:
+        if profile.startswith(("ws://", "wss://", "http://", "https://")):
+            return profile
+        env_key = f"CDP_ENDPOINT_{profile.upper().replace('-', '_')}"
+        endpoint = os.environ.get(env_key) or os.environ.get("CDP_ENDPOINT")
+        if not endpoint:
+            raise AdapterLaunchError(
+                f"No CDP endpoint configured for profile {profile!r}; "
+                f"set {env_key} or CDP_ENDPOINT to a ws:// CDP URL"
+            )
+        return endpoint
+
     # ------------------------------------------------------------------ close
     async def close(self) -> None:
         """Tear down. Honors the v2.4.1 attach contract: only closes owned pages.
@@ -180,6 +205,7 @@ class CDPBridgeAdapter:
         return {
             "backend": self.name,
             "connected": connected,
+            "running": connected,  # back-compat alias; "connected" is canonical
             "endpoint": self._endpoint,
             "owns_page": self._owns_page,
         }

{agentic_stealth_browser-2.5.0 → agentic_stealth_browser-2.6.0}/production/adapters/playwright_mcp.py

@@ -20,6 +20,7 @@ from production.adapters._jsonrpc_stdio import JsonRpcStdioClient
 from production.adapters.base import (
     AdapterCapabilityError,
     AdapterLaunchError,
+    AdapterToolError,
     Capability,
 )
 
@@ -35,11 +36,13 @@ def _subprocess_env() -> dict[str, str]:
     }
 
 
-# Pin a specific playwright-mcp version. The latest is fine; pin for
-# reproducibility. Update this when a new release is tested.
+# Pinned playwright-mcp version (not @latest — @latest is not a pin and lets
+# upstream tool-name/behavior changes silently break this adapter). Update
+# this deliberately when a new release has been tested against the tool
+# names below.
 PLAYWRIGHT_MCP_NPX_ARGS = [
     "-y",
-    "@playwright/mcp@latest",
+    "@playwright/mcp@0.0.78",
     "--isolated",
 ]
 
@@ -130,7 +133,7 @@ class PlaywrightMCPAdapter:
                     "protocolVersion": "2024-11-05",
                     "clientInfo": {
                         "name": "agentic-stealth-browser",
-                        "version": "2.5.0",
+                        "version": "2.6.0",
                     },
                     "capabilities": {},
                 },
@@ -175,34 +178,45 @@ class PlaywrightMCPAdapter:
             pass  # already dead
 
     # ------------------------------------------------------------------ actions
+    # Verified against @playwright/mcp 0.0.78 (playwright-core coreBundle.js
+    # tool schemas, packages/playwright-core/src/tools/backend/{snapshot,navigate}.ts):
+    # browser_click / browser_type take `target` (required) + `element`
+    # (optional, human-readable description) — no `selector` key. `target` is
+    # NOT limited to snapshot refs: targetLocators() only treats it as a ref
+    # when it matches /^(f\d+)?e\d+$/, otherwise it's used directly as a
+    # Playwright selector string. So a CSS selector in `target` works with no
+    # browser_snapshot round-trip.
     async def navigate(self, url: str) -> None:
         self._require_capability(Capability.NAVIGATE)
-        await self._call_tool("playwright_navigate", {"url": url})
+        await self._call_tool("browser_navigate", {"url": url})
 
     async def click(self, selector: str) -> None:
         self._require_capability(Capability.CLICK)
-        await self._call_tool("playwright_click", {"selector": selector})
+        await self._call_tool(
+            "browser_click", {"element": selector, "target": selector}
+        )
 
     async def fill(self, selector: str, value: str) -> None:
         self._require_capability(Capability.FILL)
-        await self._call_tool("playwright_fill", {"selector": selector, "value": value})
+        await self._call_tool(
+            "browser_type", {"element": selector, "target": selector, "text": value}
+        )
 
     async def screenshot(self, path: Optional[str] = None) -> str:
         self._require_capability(Capability.SCREENSHOT)
         if path is None:
             path = "screenshot.png"
-        # playwright-mcp exposes playwright_take_screenshot (or browser_take_screenshot,
-        # depending on version). Try the common names; the test will accept any.
-        try:
-            await self._call_tool("browser_take_screenshot", {"filename": path})
-        except RuntimeError:
-            await self._call_tool("playwright_take_screenshot", {"filename": path})
+        # 0.0.78 schema: browser_take_screenshot takes `filename` (optional str).
+        # No fallback tool name needed — pinned version only exposes this one.
+        await self._call_tool("browser_take_screenshot", {"filename": path})
         return str(path)
 
     async def status(self) -> dict[str, Any]:
+        alive = self._proc is not None and self._proc.returncode is None
         return {
             "backend": self.name,
-            "running": self._proc is not None and self._proc.returncode is None,
+            "connected": alive,
+            "running": alive,  # back-compat alias; "connected" is canonical
             "headless": self._headless,
             "profile": self._profile,
         }
@@ -216,7 +230,12 @@ class PlaywrightMCPAdapter:
         response = await self._client.request(
             "tools/call", {"name": name, "arguments": arguments}
         )
-        return response.get("result", {})
+        result = response.get("result", {})
+        if result.get("isError"):
+            raise AdapterToolError(
+                f"MCP tool {name!r} failed: {result.get('content')!r}"
+            )
+        return result
 
     def _require_capability(self, cap: Capability) -> None:
         """Raise AdapterCapabilityError when the active adapter does not

{agentic_stealth_browser-2.5.0 → agentic_stealth_browser-2.6.0}/production/mcp_server.py

@@ -29,7 +29,9 @@ from mcp_security import (
     MCPSecurityContext,
     sanitize_tool_description,
 )
+from production.approval_gate import ApprovalDecision, ApprovalGate
 from production.mcp_input_validator import InputValidationError, validate_tool_input
+from production.policy_engine import PolicyEngine
 
 
 JSONRPC_VERSION = "2.0"
@@ -294,6 +296,28 @@ class StealthMCPServer:
             self._bundled_workflow_root = None
         self._tools: Dict[str, ToolSpec] = self._build_tools()
 
+        # Security gates wired into the dispatch path (see handle_jsonrpc tools/call
+        # and _tool_stealth_replay). Posture:
+        #   - PolicyEngine: step-type / domain allow-lists. Enforced by default from
+        #     policy YAML in ~/.agentic-browser/policies. With no policy files the
+        #     default policy allows everything (fail-open), so normal flows are unchanged.
+        #     Set STEALTH_MCP_POLICY to activate a named loaded policy.
+        #   - ApprovalGate: sensitive-action approval. Permissive by default — there is
+        #     no human in the loop over headless stdio, so we auto-approve to avoid
+        #     deadlocking launch/navigate/replay. An operator (SDK/dashboard) enables
+        #     real enforcement by installing an approval callback via
+        #     self._approval_gate.set_allow_callback(...).
+        self._policy_engine = PolicyEngine()
+        try:
+            self._policy_engine.load_policies()
+        except Exception:
+            pass
+        active_policy = os.getenv("STEALTH_MCP_POLICY")
+        if active_policy:
+            self._policy_engine.set_active(active_policy)
+        self._approval_gate = ApprovalGate(auto_approve_known_domains=True)
+        self._approval_gate.set_allow_callback(lambda req: ApprovalDecision.ALLOWED)
+
     def _get_agent_browser_cls(self):
         if self._agent_browser_cls is not None:
             return self._agent_browser_cls
@@ -1507,6 +1531,38 @@ class StealthMCPServer:
 
         workflow = load_workflow(str(resolved_workflow_path))
 
+        # Security gate: enforce policy (step-type / domain allow-lists) on every step
+        # before executing any of them. Default policy is fail-open; operator policy
+        # YAML makes this deny blocked step types / domains and require approval.
+        for idx, step in enumerate(workflow.steps):
+            decision = self._policy_engine.check_step(
+                step.type, str(step.params.get("url", ""))
+            )
+            if not decision["allowed"]:
+                raise ToolError(
+                    "MCP_POLICY_DENIED",
+                    f"Workflow step {idx} ('{step.type}') denied by policy: {decision['reason']}",
+                    {
+                        "step_index": idx,
+                        "step_type": step.type,
+                        "reason": decision["reason"],
+                    },
+                )
+            if decision.get("approval_required"):
+                appr = self._approval_gate.check_sensitive(
+                    step.type, step.params, str(session_name or "")
+                )
+                if appr.decision != ApprovalDecision.ALLOWED:
+                    raise ToolError(
+                        "MCP_APPROVAL_REQUIRED",
+                        f"Workflow step {idx} ('{step.type}') requires approval: {appr.reason}",
+                        {
+                            "step_index": idx,
+                            "step_type": step.type,
+                            "request_id": appr.request_id,
+                        },
+                    )
+
         if session_name:
             resolved_name, browser = await self._resolve_browser(session_name)
         else:
@@ -1755,6 +1811,26 @@ class StealthMCPServer:
                     msg_id, self._tool_result(payload, is_error=True)
                 )
 
+            # Security gate: sensitive-action approval before handler execution.
+            # No-op for non-sensitive tools; permissive unless an operator installs an
+            # approval callback (see __init__). Blocks on DENIED/PENDING when enforced.
+            gate = self._approval_gate.check_sensitive(
+                tool_name, validated_args, str(validated_args.get("session_name") or "")
+            )
+            if gate.decision != ApprovalDecision.ALLOWED:
+                payload = self._tool_error_payload(
+                    "MCP_APPROVAL_REQUIRED",
+                    f"Action '{tool_name}' requires approval: {gate.reason}",
+                    {
+                        "tool": tool_name,
+                        "request_id": gate.request_id,
+                        "decision": gate.decision.value,
+                    },
+                )
+                return self._jsonrpc_result(
+                    msg_id, self._tool_result(payload, is_error=True)
+                )
+
             try:
                 payload = await tool.handler(validated_args)
                 return self._jsonrpc_result(

{agentic_stealth_browser-2.5.0 → agentic_stealth_browser-2.6.0}/production/mcp_session_isolation.py

@@ -5,6 +5,17 @@ Prevents cross-session data access:
 - One session's tool calls cannot access another session's browser instance.
 - session_name must match the caller's authorized session.
 - Token-based session binding for concurrent clients.
+
+NOT YET INTEGRATED (honesty note): SessionEnforcer is defined and unit-tested but
+is NOT called from the MCP dispatch path in production/mcp_server.py. Its model
+isolates *concurrent client contexts* from each other via per-context tokens, but
+the current MCP transport is single-client stdio and carries no per-call context
+token to key check_access() on. With one trust domain there is nothing to isolate
+from, and _resolve_browser() already rejects unknown/closed sessions — so wiring a
+constant global token here would be security theater, not enforcement. This class
+becomes meaningful only under a multi-client transport (e.g. HTTP/SSE) that supplies
+a real per-client context token to bind_session()/check_access(). Until then it
+enforces nothing at runtime; do not rely on it for isolation.
 """
 
 from __future__ import annotations
@@ -48,6 +59,11 @@ class SessionEnforcer:
     Each call context is associated with a token. Tools can only operate on
     sessions bound to their call context's token. A single client/context cannot
     access another context's browser instances.
+
+    NOT WIRED: no call site in production/mcp_server.py's dispatch path. Requires a
+    multi-client transport that supplies a per-context token — the current stdio
+    transport does not. See the module docstring. This is a defined-but-inert
+    security control, not an active one.
     """
 
     def __init__(self) -> None:

{agentic_stealth_browser-2.5.0 → agentic_stealth_browser-2.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-stealth-browser"
-version = "2.5.0"
+version = "2.6.0"
 description = "Production-grade, human-mimicking browser automation framework for autonomous agents. Survives modern anti-bot systems."
 readme = "README.md"
 license = "MIT"