fix: wire proxy auth credentials for local browser sessions

[optimusbuilder]

why

localBrowserLaunchOptions.proxy accepts username and password in the schema, but only proxy.server was forwarded to Chromium. Authenticated proxies failed silently because credentials were never used.

what changed

• Extract proxy.username/password from localBrowserLaunchOptions in V3Context
• Enable CDP Fetch with handleAuthRequests on each target attach
• Respond to Fetch.authRequired with stored credentials
• Unit tests for credential extraction edge cases

test plan

• pnpm exec vitest run dist/esm/tests/unit/proxy-auth.test.js

---

Summary by cubic

Fixes authenticated proxy support for local Chrome sessions by wiring proxy.username and proxy.password from localBrowserLaunchOptions and handling CDP Fetch.authRequired. Auth-required proxies now work without manual workarounds.

• Bug Fixes
  • Store credentials from localBrowserLaunchOptions.proxy.
  • Enable CDP Fetch with handleAuthRequests and answer authRequired with stored creds.
  • Resume paused requests with Fetch.continueRequest.
  • Add unit tests for credential extraction edge cases.

^{Written for commit d03ba32. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: d03ba32

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server-v3	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

This PR is from an external contributor and must be approved by a stagehand team member with write access before CI can run.
Approving the latest commit mirrors it into an internal PR owned by the approver.
If new commits are pushed later, the internal PR stays open but is marked stale until someone approves the latest external commit and refreshes it.

[cubic-dev-ai]

No issues found across 3 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Config as LocalBrowserLaunchOptions
    participant Ctx as V3Context
    participant CDP as CDPSession (Target)
    participant Proxy as Auth Proxy Server
    participant Browser as Chromium Browser

    Note over Ctx: Constructor: Extract proxy credentials
    Ctx->>Config: Read proxy config
    alt Has proxy.username and proxy.password
        Ctx->>Ctx: Store credentials in proxyCredentials field
    else Missing credentials
        Ctx->>Ctx: proxyCredentials = null (no auth flow)
    end

    Note over Ctx,Browser: Target Attach Flow (per session)

    Ctx->>CDP: installTargetSessionListeners(session)
    opt proxyCredentials exists
        Ctx->>CDP: Register "Fetch.authRequired" listener
        Ctx->>CDP: Register "Fetch.requestPaused" listener
        Ctx->>Ctx: Queue Fetch.enable({ handleAuthRequests: true })
    end

    Note over Ctx: Pre-resume dispatch phase
    Ctx->>Ctx: Await all queued pre-resume ops (core, headers, proxy, init, piercer)

    Note over Browser,Proxy: Runtime Auth Flow

    Browser->>Proxy: HTTP request (initiated by page)
    Proxy-->>Browser: 407 Proxy Authentication Required

    Browser->>CDP: Fetch.authRequired event
    CDP->>Ctx: Fire "Fetch.authRequired" listener
    Ctx->>Ctx: Extract credentials from stored proxyCredentials
    Ctx->>CDP: Fetch.continueWithAuth(requestId, ProvideCredentials + username/password)

    CDP->>Browser: Forward auth credentials
    Browser->>Proxy: Re-request with Proxy-Authorization header
    alt Auth successful
        Proxy-->>Browser: 200 OK (proxy tunnel established)
        Browser->>CDP: Fetch.requestPaused
        CDP->>Ctx: Fire "Fetch.requestPaused" listener
        Ctx->>CDP: Fetch.continueRequest(requestId)
        CDP-->>Browser: Resume paused request
    else Auth failed
        Proxy-->>Browser: 407 or 403 (invalid credentials)
        Browser->>CDP: Fetch.authRequired again
        Ctx->>CDP: Retry with same credentials (no retry limit)
        alt Repeated failure
            Proxy-->>Browser: Connection refused
            Browser-->>Ctx: Request fails (no alternative flow)
        end
    end

    Note over Ctx: Edge case: target detach during auth
    Note over Ctx: catch(() => {}) on CDP sends silently handles detached sessions

Loading

_{Re-trigger cubic}