Challenge Mode

Challenge mode adds an additional gate for HTTP tunnels. The intention is to block unwanted automated traffic before it reaches upstream services and before the engine evaluates authentication policies.

Challenge mode is browser-oriented. When a browser reaches a protected tunnel without a valid challenge session, the engine redirects it to an rstream verification page. The page runs the challenge automatically, returns to the original tunnel URL, and the engine stores the result in a dedicated challenge cookie for that tunnel host.

Challenge mode is configured as a boolean tunnel property and is exposed on the CLI through rstream forward --challenge-mode.

rstream forward 8080 --http --challenge-mode

Challenge mode is available for HTTP tunnels when the project plan allows it and when the engine has an active challenge backend configured.

Runtime flow

For a regular browser navigation, the browser first requests the protected tunnel URL as usual. The engine checks whether that request already carries a valid challenge cookie for the tunnel host. If the cookie is missing or invalid, the engine creates a challenge request and redirects the browser to the rstream verification page.

The verification page completes the challenge automatically and sends the browser back to the original tunnel URL. At that point, the engine validates the challenge callback, sets a dedicated challenge cookie, and lets the browser retry the original request. Once the cookie is valid for the current tunnel host, matching requests can be forwarded upstream.

The cookie is separate from rstream Auth. It proves that the browser completed the challenge for the tunnel host; it does not identify the user and does not grant account access by itself.

Requests that cannot safely be redirected, such as non-GET HTTP methods and HTTP upgrade handshakes, are rejected until a valid challenge cookie already exists. This avoids forwarding unverified traffic and avoids replaying request bodies after an external verification step.

Relationship with authentication

Challenge mode does not replace token authentication or rstream Auth. Authentication decisions are still driven by the tunnel authentication settings.

The engine evaluates edge access policies first, then challenge mode, then tunnel authentication. When token authentication is enabled on the tunnel, a valid and authorized bearer token can bypass the browser challenge because token authentication is the explicit machine-client path.

When no valid token is present, a tunnel that combines challenge mode and rstream Auth first completes the browser challenge and then runs the rstream Auth session flow.

rstream forward 8080 --http --challenge-mode --rstream-auth

rstream forward 8080 --http --challenge-mode --token-auth

Challenge sessions use their own cookie and do not reuse the rstream Auth session cookie. Clearing or expiring one session does not implicitly clear the other.

Non-browser clients

Challenge mode is intended for browsers. Automated clients should use token authentication instead of trying to complete the browser challenge flow.

For mixed access, enable both --challenge-mode and --token-auth. Browsers without a token receive the browser challenge, while API clients can present an authorized bearer token on each request.

curl -H "Authorization: Bearer <token>" https://<tunnel-host>/