Make auth handoff default to real auth links

Author: federicodeponte

README.md

@@ -81,7 +81,7 @@ sequenceDiagram
   C-->>B: page state
   B-->>A: snapshot or result
   alt login or challenge required
-    A->>B: auth_request or lease_control_request
+    A->>B: auth_request
     B-->>H: one-time portal URL
     H->>C: human completes login
   end

ax_browser_broker/api.py

@@ -41,7 +41,7 @@
 )
 from .docs import docs
 from .feedback import FeedbackError, list_issues, report_issue, update_issue
-from .identities import IdentityError, invalidate_identity_replicas, redacted_status
+from .identities import IdentityError, invalidate_identity_replicas, redacted_status, require_identity
 from .lease_control import (
     LeaseControlError,
     complete_control_session,
@@ -152,7 +152,7 @@ class AuthRequest(BaseModel):
     reason: str = "login_required"
     identity_id: str | None = None
     profile: str | None = None
-    mode: str = "lease_control"
+    mode: str = "vnc"
     ttl_seconds: int = Field(default=900, ge=60, le=14400)
     control_ttl_seconds: int = Field(default=900, ge=60, le=3600)
     wait_until: str = "domcontentloaded"
@@ -233,6 +233,8 @@ def _active_identity_lease_id(identity_id: str | None) -> str | None:
 
 
 def _active_identity_control_redirect(auth_request_data: dict[str, Any], error: AuthError) -> RedirectResponse | None:
+    if str(auth_request_data.get("mode") or "vnc") == "vnc":
+        return None
     identity_id = str(auth_request_data.get("identity_id") or "")
     message = str(error)
     if not identity_id or "actively leased" not in message:
@@ -268,11 +270,13 @@ def _url_host(url: str | None) -> str:
 
 
 async def _legacy_vnc_auth_request(request: AuthRequest) -> dict[str, Any]:
+    if request.identity_id:
+        require_identity(request.identity_id)
     result = create_auth_request(request.owner, request.url, request.reason, request.identity_id, mode=request.mode)
     _safe_record_event(
         source=request.owner,
         event_type="auth",
-        message="Legacy VNC auth request created",
+        message="Auth handoff request created",
         url=request.url,
         tags=["auth", "vnc", request.reason],
         data={"token": result.get("token"), "status": result.get("status"), "identity_id": request.identity_id},
@@ -365,11 +369,11 @@ async def _active_identity_control_response(request: AuthRequest) -> dict[str, A
 
 
 async def _open_auth_lease_control(request: AuthRequest) -> dict[str, Any]:
+    if request.mode == "vnc":
+        return await _legacy_vnc_auth_request(request)
     active_response = await _active_identity_control_response(request)
     if active_response:
         return active_response
-    if request.mode == "vnc":
-        return await _legacy_vnc_auth_request(request)
     lease_obj = await create_lease(
         LeaseRequest(owner=request.owner, ttl_seconds=request.ttl_seconds, identity_id=request.identity_id)
     )
@@ -404,10 +408,10 @@ async def _open_auth_lease_control(request: AuthRequest) -> dict[str, Any]:
         _safe_record_event(
             source=request.owner,
             event_type="session",
-            message="Auth request opened lease control",
+            message="Explicit lease-control auth fallback opened",
             lease_id=lease_id,
             url=navigation.get("url") or request.url,
-            tags=["auth", "lease-control", "default"],
+            tags=["auth", "lease-control", "explicit"],
             data={
                 "slot": lease_obj.get("name"),
                 "identity_id": request.identity_id,

ax_browser_broker/cli.py

@@ -232,7 +232,7 @@ def build_parser() -> argparse.ArgumentParser:
     open_cmd.add_argument("--no-verify", action="store_true", help="Skip the post-navigation snapshot receipt")
     open_cmd.set_defaults(func=cmd_open)
 
-    auth = sub.add_parser("auth", help="Create an auth handoff or active lease-control response")
+    auth = sub.add_parser("auth", help="Create a real /auth/<token> login handoff")
     auth.add_argument("url")
     auth.add_argument("--identity", default=None)
     auth.add_argument("--owner", default="openbrowser-cli")
@@ -242,8 +242,8 @@ def build_parser() -> argparse.ArgumentParser:
     auth.add_argument(
         "--mode",
         choices=["lease_control", "vnc"],
-        default="lease_control",
-        help="lease_control is the default; vnc is the legacy full-login-view fallback",
+        default="vnc",
+        help="vnc is the default real login portal; lease_control is only for explicit current-tab control fallback",
     )
     auth.set_defaults(func=cmd_auth)
 

ax_browser_broker/docs.py

@@ -58,8 +58,8 @@
         ],
         "rules": [
             "Use broker identities such as work-main or qa-generic when account state is needed.",
-            "Use auth_request for login or password handoff; auth_request returns lease_control by default.",
-            "Use lease_control_request when an already-leased browser hits a human challenge or login prompt that must be handled in the current tab.",
+            "Use auth_request for login or password handoff; auth_request returns a real /auth/<token> portal by default.",
+            "Use lease_control_request only when an already-leased browser needs human current-tab control without credential entry.",
             "Use OpenBrowser wrappers instead of aiming custom scripts directly at raw pool CDP ports.",
             "For chat/editor submission, prefer broker keyboard tools over DOM fill because modern editors maintain internal state.",
             "For Slack header/tab controls, dismiss open ReactModal/popovers with Escape before selector clicks.",
@@ -118,7 +118,7 @@
         "notes": [
             "The CLI talks to the local broker API and reads the local server-side API key file when needed.",
             "Use open --control for simple 'open this for me' requests; it returns a verified control URL in one command.",
-            "openbrowser auth returns an interactive lease-control URL by default. Use --mode vnc only for the legacy full-login-view fallback.",
+            "openbrowser auth returns a real /auth/<token> login portal by default. Use open --control or lease-control for current-tab control links.",
             "Use it for status, docs, auth handoffs, active lease-control links, and quick smoke checks.",
             "Use Broker MCP directly for normal click/type/screenshot workflows when tools are available.",
         ],
@@ -127,22 +127,21 @@
         "title": "Human Auth Handoff",
         "steps": [
             "When an agent hits a login wall, call auth_request with owner, url, reason, and identity_id.",
-            "auth_request returns lease_control by default: a broker lease is opened or reused, navigated to the requested URL when safe, verified with a compact snapshot, and exposed through the normal control portal.",
-            "If the requested identity is already leased, auth_request returns lease_control for that active browser instead of opening a competing Chrome profile.",
-            "If the active leased browser is on a different host than the requested URL, auth_request returns takeover_required=true and does not navigate the active browser.",
-            "If no identity_id is supplied, auth_request opens a neutral broker browser and returns a warning instead of using a personal authenticated profile.",
-            "Send the returned portal_url to the human operator only after checking status, current_url/navigation, snapshot, and takeover_required.",
-            "Use mode=vnc only when the legacy full-login-view fallback is explicitly needed.",
-            "During legacy VNC identity auth, the broker pauses the matching pool slot with a maintenance marker so headless Chrome cannot re-lock the profile.",
+            "auth_request returns a real /auth/<token> login portal by default. Send this link when the user must sign in, enter a password, use a passkey, solve 2FA, or complete a provider login flow.",
+            "If the requested identity is already leased, do not convert login auth into lease-control. Release your own stale lease first, or wait if another agent owns the lease.",
+            "Use lease_control_request only when the user explicitly needs to control an already-open current tab, not for credential entry.",
+            "If no identity_id is supplied, auth_request creates a neutral auth portal and does not use a personal authenticated profile.",
+            "Send the returned portal_url only when it starts with /auth/ and not /auth/lease-control/ for login tasks.",
+            "Use mode=lease_control only for the explicit current-tab fallback. Do not use it for login.",
+            "During identity auth, the broker pauses the matching pool slot with a maintenance marker so headless Chrome cannot re-lock the profile.",
             "If the identity has proxy_ref, the legacy temporary auth Chrome also uses that proxy through ax-proxy-forwarder.",
-            "If a legacy VNC identity auth handoff is refused before VNC starts, the temporary VNC password file is removed.",
-            "When legacy VNC completion runs, the broker stops VNC/websockify/Chrome/Xvfb helper processes and removes the temporary password file.",
-            "After a lease-control handoff, continue from the same lease_id/current tab. Do not create a second lease or navigate away from a meaningful page.",
+            "If an identity auth handoff is refused before VNC starts, the temporary VNC password file is removed.",
+            "When auth completion runs, the broker stops VNC/websockify/Chrome/Xvfb helper processes and removes the temporary password file.",
+            "After auth completion, lease the same identity, snapshot first, and continue from the authenticated state. After lease-control, continue from the same lease_id/current tab.",
             "After browser work, confirm state with snapshot or screenshot and run broker_audit.",
         ],
         "examples": [
             {"tool": "auth_request", "args": {"owner": "agent-name", "url": "https://example.com/login", "reason": "profile_login", "identity_id": "work-main"}},
-            {"tool": "auth_request", "args": {"owner": "agent-name", "url": "https://example.com/login", "reason": "legacy_vnc_login", "identity_id": "work-main", "mode": "vnc"}},
             {"tool": "lease_control_request", "args": {"owner": "agent-name", "lease_id": "<lease_id>", "ttl_seconds": 900}},
         ],
     },

ax_browser_broker/mcp_server.py

@@ -257,13 +257,13 @@ def auth_request(
     url: str,
     reason: str = "login_required",
     identity_id: str | None = None,
-    mode: Literal["lease_control", "vnc"] = "lease_control",
+    mode: Literal["vnc", "lease_control"] = "vnc",
     ttl_seconds: int = 900,
     control_ttl_seconds: int = 900,
     wait_until: str = "domcontentloaded",
     verify: bool = True,
 ) -> dict[str, Any]:
-    """Create a human auth handoff. Defaults to lease-control; pass mode='vnc' only for the legacy login-view fallback."""
+    """Create a real /auth/<token> login handoff. Use mode='lease_control' only for explicit current-tab control fallback."""
     return _request(
         "POST",
         "/auth/request",

ax_browser_broker/remote_mcp_server.py

@@ -228,13 +228,13 @@ def auth_request(
     url: str,
     reason: str = "login_required",
     identity_id: str | None = None,
-    mode: Literal["lease_control", "vnc"] = "lease_control",
+    mode: Literal["vnc", "lease_control"] = "vnc",
     ttl_seconds: int = 900,
     control_ttl_seconds: int = 900,
     wait_until: str = "domcontentloaded",
     verify: bool = True,
 ) -> dict[str, Any]:
-    """Create a human auth handoff. Defaults to lease-control; pass mode='vnc' only for the legacy login-view fallback."""
+    """Create a real /auth/<token> login handoff. Use mode='lease_control' only for explicit current-tab control fallback."""
     return _request(
         "POST",
         "/auth/request",

docs/browser-routing.md

@@ -9,7 +9,7 @@ flowchart TD
   NeedAuth -->|Yes| Identity["Lease named identity"]
   Identity --> Login{"Login wall?"}
   Login -->|No| Act["Navigate, click, type, screenshot"]
-  Login -->|Yes| Handoff["auth_request or lease_control_request"]
+  Login -->|Yes| Handoff["auth_request -> /auth/<token>"]
   Generic --> Act
   Handoff --> Act
   Act --> Release["Release lease"]
@@ -31,7 +31,7 @@ flowchart TD
 1. Lease before browser work.
 2. Use identities only when account state or proxy routing is required.
 3. Use `auth_request` for login, passkeys, 2FA, or password entry.
-4. Use `lease_control_request` when a human must control the currently leased tab.
+4. Use `lease_control_request` only when a human must control the currently leased tab without entering credentials.
 5. Release every lease.
 6. Run `broker_audit` after browser-agent work.
 7. Do not connect custom scripts directly to raw pool CDP ports during normal agent work.