WebX Managed Proxies

WebX can lease an upstream proxy for a session by geography instead of the caller supplying credentials — and, uniquely, records the observed exit country so the session receipt proves where the browser actually egressed, not merely where it was asked to.

What it adds over an external proxy

WebX already accepts an external --proxy-server and answers authenticated 407 challenges. The managed layer adds, on top of that:

• A ProxyProvider abstraction (default: an operator-supplied static pool; a residential vendor drops in behind the same trait).
• Geo-routing — select a pool entry by country / state / city.
• Sticky egress — a stickyKey maps a caller to a stable IP across leases.
• Bandwidth metering — real wire bytes (proxyBytes) counted from the browser's CDP Network events.
• Egress verification — an out-of-band IP-geo lookup through the leased proxy records the actual exit country.
• A proxy receipt on the session: provider, requested vs observed country, a one-way lease hash, bytes, and rotation policy.

Credentials live only in the pool config (a secret) and the leased launch args — never in logs, session metadata, or the receipt (which exposes a hashed leaseHash, never the username/password).

Enabling it

Managed proxies are opt-in and advertised only when a pool is configured; otherwise a managed request fails honestly (400 managed_proxy_unavailable).

A pool/inventory entry:

[
  {
    "server": "http://gateway.vendor:8080",
    "username": "u", "password": "p",
    "country": "US", "state": "CA", "city": "SAN_FRANCISCO",
    "provider": "vendor-a",
    "pool": "residential-login",
    "region": "us-east-1",
    "healthCheckUrl": "https://inventory.vendor.example/health",
    "credentialVersion": "2026-08-03"
  }
]

Requesting a managed proxy

Use the Browserbase-compatible proxies field on session create. true leases any managed egress; an object selects a geography:

// POST /v1/sessions
{
  "proxies": [
    {
      "type": "webx",
      "geolocation": { "country": "US", "state": "CA", "city": "SAN_FRANCISCO" },
      "rotation": "per_session",   // per_session (default) | per_request | on_failure
      "stickyKey": "login-flow-7"  // optional: stable egress for this caller
    }
  ]
}

An external proxy is still supported and applied verbatim:

{ "proxies": [{ "type": "external", "server": "http://host:8080",
                "username": "u", "password": "p" }] }

The proxy receipt

The create/get response carries a proxy object (present only for a managed lease):

{
  "proxyBytes": 148223,
  "proxy": {
    "provider": "vendor-a",
    "requestedGeo": "US-CA",
    "observedCountry": "US",   // verified THROUGH the proxy; null if unverified
    "leaseHash": "1654bddb4ea2f043",
    "bytes": 148223,
    "rotations": 0,
    "rotationPolicy": "per_session"
  }
}

observedCountry is the evidence: WebX fetched an IP-geo endpoint through the leased proxy and recorded the real exit country. It is never fabricated — a failed or unconfigured check leaves it null rather than echoing the request.

Behavior & limits (MVP)

• The static pool honors per-session rotation (a session keeps its egress IP); per_request / on_failure are recorded on the receipt for a vendor adapter that implements them, and treated as per-session by the static pool.
• Inventory can refresh from operator files or signed HTTPS endpoints without a restart. Sticky callers keep their existing lease hash while the same entry remains present; new credentials or new pools are picked up on the next lease.
• Entries whose explicit healthCheckUrl fails are quarantined temporarily and excluded from leasing; requests fail closed if every matching entry is quarantined.
• Transport-failure health scoring can quarantine endpoints in-process; geo mismatch quarantines immediately. Identity-preserving failover prefers the minimum identity-distance healthy route and fails closed when none exists within the safe distance budget (country changes are never silent).
• Optional inventory fields: proxyType (datacenter|isp|residential| mobile), maxSessions, asn, and price hints (pricePerSession / pricePerGb / pricePerMinute) for cost-aware scheduling when budgets carry network_usd.
• A request whose geography/pool no live entry satisfies is rejected (400 managed_proxy_unavailable) — never silently downgraded to a different region.
• proxyBytes is metered from the browser's proxied Network.loadingFinished wire bytes; it accrues only while the authenticated-proxy pump is attached (i.e. for authenticated pool entries, the normal case).
• The lease is released — and its receipt cleared — on session teardown (explicit release, timeout, or graceful shutdown).
• Qualification without WEBX_PROXY_GEO_CHECK_URL returns honest qualified: false / unevaluable — never fabricates exit geography.

Session identity coherence

Browser fingerprint, managed lease, geography, DNS mode, and persistence policy compose into a single SessionIdentity (WEBX_IDENTITY_POLICY=permissive|coherent|strict). Default is permissive (backward compatible). Coherent/strict fail closed on high-value contradictions (timezone vs country, mobile proxy + desktop UA, context country jumps, Chrome major vs Browser.getVersion when observed). Persistent contexts store a secret-free webx-network-identity.json so reuse rebinds a compatible network family beside cookies.