Wrangler WebSocket Auth Relay

[petebacondarwin]

Problem

The current wrangler login flow requires Wrangler to host a local HTTP server on localhost:8976 to receive the OAuth callback. This doesn't work well in containers, remote VMs, Codespaces, or other environments where localhost isn't accessible from the user's browser.

Solution Overview

Introduce a Cloudflare Worker relay (auth.devprod.cloudflare.dev) with a Durable Object that acts as a WebSocket bridge between Wrangler (in any environment) and the OAuth callback (from the user's browser).

Flow

Security Model

• State = Session ID: The state param (32-char crypto-random, generated by Wrangler the same way it is today) identifies the DO instance and provides CSRF protection. Wrangler validates the returned state matches what it generated.
• Auth worker only sees the auth code, never the access token. Auth codes are single-use and short-lived.
• PKCE ensures only Wrangler (holding code_verifier) can exchange the code for a token. The code_verifier never leaves Wrangler.
• One WebSocket per session: The DO rejects additional WebSocket connections.
• 5-minute TTL: DO alarm auto-cleans up stale sessions.

---

Part 1: New Package — packages/wrangler-auth-worker/

File Structure

packages/wrangler-auth-worker/
├── package.json
├── tsconfig.json
├── eslint.config.mjs
├── wrangler.jsonc
├── src/
│   ├── index.ts              # Worker fetch handler + re-export DO
│   └── auth-session.ts       # AuthSession Durable Object
└── tests/
    ├── vitest.config.mts
    └── auth-session.test.ts

src/index.ts — Worker Entry Point

Routes:

Path	Purpose
GET /session/:state (with Upgrade: websocket header)	WebSocket upgrade — route to DO via env.AUTH_SESSION.idFromName(state)
GET /callback?code=X&state=Y	OAuth callback — extract state, route to DO, return 307 redirect
Everything else	404

Callback handling mirrors the current Wrangler local server behavior (no HTML pages, only 307 redirects):

• If ?error=access_denied&state=Y: route to DO (sends error via WebSocket), return 307 redirect to https://welcome.developers.workers.dev/wrangler-oauth-consent-denied
• If ?code=X&state=Y: route to DO (sends code via WebSocket), return 307 redirect to https://welcome.developers.workers.dev/wrangler-oauth-consent-granted

src/auth-session.ts — AuthSession Durable Object

Uses the Hibernation API for efficient WebSocket handling.

export class AuthSession extends DurableObject {
	// fetch(request):
	//   Handles both WebSocket upgrades and callback forwarding.
	//
	//   Path /connect (WebSocket upgrade from Wrangler):
	//     - Reject if a WebSocket is already connected (ctx.getWebSockets().length > 0)
	//     - Accept WebSocket via new WebSocketPair + ctx.acceptWebSocket()
	//     - Set 5-minute alarm for cleanup
	//
	//   Path /callback (forwarded from worker fetch handler):
	//     - Extract code or error from query params
	//     - Send JSON message to connected WebSocket: { code } or { error }
	//     - Close the WebSocket
	//     - Return minimal response (worker handles the 307 redirect)
	// webSocketClose(ws):
	//   Clean up session state
	// alarm():
	//   Close any lingering WebSocket, clean up
}

Key behaviors:

• Only one WebSocket connection allowed per session (reject extras with 409)
• On receiving callback data: send JSON message down the WebSocket, then close it
• 5-minute alarm for auto-cleanup of stale sessions

wrangler.jsonc

{
	"name": "wrangler-auth-worker",
	"main": "src/index.ts",
	"compatibility_date": "2025-03-01",
	"compatibility_flags": ["nodejs_compat"],
	"workers_dev": false,
	"routes": [
		{
			"pattern": "auth.devprod.cloudflare.dev/*",
			"zone_name": "devprod.cloudflare.dev",
		},
	],
	"durable_objects": {
		"bindings": [{ "name": "AUTH_SESSION", "class_name": "AuthSession" }],
	},
	"migrations": [{ "tag": "v1", "new_classes": ["AuthSession"] }],
}

package.json

{
	"name": "@cloudflare/wrangler-auth-worker",
	"private": true,
	"workers-sdk": { "prerelease": true, "deploy": true },
	"devDependencies": {
		"wrangler": "workspace:*",
		"@cloudflare/workers-types": "catalog:default",
		"@cloudflare/workers-tsconfig": "workspace:*",
		"@cloudflare/eslint-config-shared": "workspace:*",
		"@cloudflare/vitest-pool-workers": "workspace:*",
		"eslint": "catalog:default",
		"typescript": "catalog:default",
		"vitest": "catalog:vitest-3"
	},
	"scripts": {
		"deploy": "wrangler deploy"
	}
}

---

Part 2: Wrangler Changes

2.1 New CLI Flag — packages/wrangler/src/user/commands.ts

Add --x-websocket-callback flag to the login command args (hidden, experimental):

"x-websocket-callback": {
  type: "boolean",
  default: false,
  hidden: true,
  description: "Use WebSocket relay for OAuth callback (useful in containers)",
},

Pass it through to login(). Eventually this becomes the default and the flag is removed.

2.2 Auth Worker URL — packages/wrangler/src/user/auth-variables.ts

Add a new configurable URL for the auth worker. A single deployment serves all environments (production and staging) since the worker only holds ephemeral relay state and is fully agnostic to the OAuth environment. FedRAMP is not a concern because OAuth login is already rejected entirely for fedramp_high users (they must use API tokens).

export const getAuthWorkerUrlFromEnv = getEnvironmentVariableFactory({
	variableName: "WRANGLER_AUTH_WORKER_URL",
	defaultValue: () => "https://auth.devprod.cloudflare.dev",
});

2.3 Parameterize redirect_uri — packages/wrangler/src/user/generate-auth-url.ts

Currently redirect_uri is hardcoded to OAUTH_CALLBACK_URL (http://localhost:8976/oauth/callback). Make it a parameter with a backward-compatible default:

interface GenerateAuthUrlProps {
	authUrl: string;
	clientId: string;
	scopes: string[];
	stateQueryParam: string;
	codeChallenge: string;
	callbackUrl?: string; // NEW — defaults to OAUTH_CALLBACK_URL
}

export const generateAuthUrl = ({
	authUrl,
	clientId,
	scopes,
	stateQueryParam,
	codeChallenge,
	callbackUrl = OAUTH_CALLBACK_URL,
}: GenerateAuthUrlProps) => {
	return (
		authUrl +
		`?response_type=code&` +
		`client_id=${encodeURIComponent(clientId)}&` +
		`redirect_uri=${encodeURIComponent(callbackUrl)}&` +
		`scope=${encodeURIComponent([...scopes, "offline_access"].join(" "))}&` +
		`state=${stateQueryParam}&` +
		`code_challenge=${encodeURIComponent(codeChallenge)}&` +
		`code_challenge_method=S256`
	);
};

2.4 WebSocket Auth Flow — packages/wrangler/src/user/user.ts

Add a new function getOauthTokenViaWebSocket() as an alternative to getOauthToken().

Pseudocode (~60 lines):

async function getOauthTokenViaWebSocket(options: {
	scopes: string[];
	clientId: string;
	browser: boolean;
	denied: { url: string; error: string };
	granted: { url: string };
}): Promise<AccessContext> {
	// 1. Generate PKCE codes (reuse existing generatePKCECodes())
	const { codeChallenge, codeVerifier } = await generatePKCECodes();

	// 2. Generate state (reuse existing generateRandomState())
	//    This also serves as the session ID for the DO
	const state = generateRandomState(RECOMMENDED_STATE_LENGTH);

	// 3. Open WebSocket to auth worker
	const authWorkerUrl = getAuthWorkerUrlFromEnv();
	const wsUrl =
		authWorkerUrl.replace("https://", "wss://") + `/session/${state}`;
	const ws = new WebSocket(wsUrl);

	// 4. Wait for connection to open
	await new Promise((resolve, reject) => {
		ws.onopen = resolve;
		ws.onerror = reject;
	});

	// 5. Build auth URL with remote callback URL
	const remoteCallbackUrl = `${authWorkerUrl}/callback`;
	const authUrl = generateAuthUrl({
		authUrl: getAuthUrlFromEnv(),
		clientId: options.clientId,
		scopes: options.scopes,
		stateQueryParam: state,
		codeChallenge,
		callbackUrl: remoteCallbackUrl,
	});

	// 6. Open browser (or print URL)
	if (options.browser) {
		logger.log(`Opening a link in your default browser: ${authUrl}`);
		await openInBrowser(authUrl);
	} else {
		logger.log(`Visit this link to authenticate: ${authUrl}`);
	}

	// 7. Wait for auth code via WebSocket (with 120s timeout)
	const result = await Promise.race([
		new Promise<{ code?: string; error?: string }>((resolve, reject) => {
			ws.onmessage = (event) => resolve(JSON.parse(event.data));
			ws.onerror = reject;
			ws.onclose = () =>
				reject(new Error("WebSocket closed before auth completed"));
		}),
		sleep(120_000).then(() => {
			throw new Error("Login timed out");
		}),
	]);

	ws.close();

	// 8. Handle error (user denied consent)
	if (result.error) {
		throw new UserError(options.denied.error);
	}

	// 9. Exchange code for token
	//    redirect_uri must match what was sent in the auth URL
	const params = new URLSearchParams({
		grant_type: "authorization_code",
		code: result.code ?? "",
		redirect_uri: remoteCallbackUrl,
		client_id: options.clientId,
		code_verifier: codeVerifier,
	});
	const response = await fetchAuthToken(params);

	// 10. Parse and return AccessContext (same logic as current flow)
	// ...
}

2.5 Wire Into login() — packages/wrangler/src/user/user.ts (~line 1136)

Branch based on --x-websocket-callback:

export async function login(props: LoginProps): Promise<boolean> {
	// ... existing validation ...

	const getToken = props.xWebsocketCallback
		? getOauthTokenViaWebSocket
		: getOauthToken;

	const tokenData = await getToken({
		scopes: props.scopes ?? DefaultScopeKeys,
		clientId: getClientIdFromEnv(),
		browser: !!props.browser,
		denied: {
			url: "https://welcome.developers.workers.dev/wrangler-oauth-consent-denied",
			error: "Error: Consent denied. ...",
		},
		granted: {
			url: "https://welcome.developers.workers.dev/wrangler-oauth-consent-granted",
		},
		// only needed for local server path:
		...(props.xWebsocketCallback
			? {}
			: {
					callbackHost: props.callbackHost ?? "localhost",
					callbackPort: props.callbackPort ?? 8976,
				}),
	});

	// ... existing token storage logic unchanged ...
}

---

Part 3: Files Summary

File	Action	Description
packages/wrangler-auth-worker/package.json	CREATE	Package manifest with deploy: true
packages/wrangler-auth-worker/wrangler.jsonc	CREATE	Worker + DO config
packages/wrangler-auth-worker/tsconfig.json	CREATE	TypeScript config
packages/wrangler-auth-worker/eslint.config.mjs	CREATE	Linting config
packages/wrangler-auth-worker/src/index.ts	CREATE	Worker fetch handler (routing, 307 redirects)
packages/wrangler-auth-worker/src/auth-session.ts	CREATE	AuthSession Durable Object (WebSocket relay)
packages/wrangler-auth-worker/tests/vitest.config.mts	CREATE	Test config using vitest-pool-workers
packages/wrangler-auth-worker/tests/auth-session.test.ts	CREATE	DO + Worker integration tests
packages/wrangler/src/user/commands.ts	MODIFY	Add --x-websocket-callback flag
packages/wrangler/src/user/auth-variables.ts	MODIFY	Add getAuthWorkerUrlFromEnv()
packages/wrangler/src/user/generate-auth-url.ts	MODIFY	Parameterize redirect_uri via callbackUrl
packages/wrangler/src/user/user.ts	MODIFY	Add getOauthTokenViaWebSocket(), branch in login()

---

Part 4: Prerequisites

OAuth Redirect URI Registration (BLOCKING)

https://auth.devprod.cloudflare.dev/callback must be registered as a valid redirect_uri for Wrangler's OAuth client IDs on Cloudflare's OAuth server at dash.cloudflare.com:

• Production client: 54d11594-84e4-41aa-b438-e81b8fa78ee7
• Staging client: 4b2ea6cc-9421-4761-874b-ce550e0e3def

Both clients use the same auth worker URL — there is no separate staging auth worker, since the worker only relays ephemeral auth codes and is agnostic to the OAuth environment.

FedRAMP does not need consideration here — OAuth login is already rejected for fedramp_high at the Wrangler CLI level (users must use API tokens instead).

This requires coordination with the team managing Cloudflare's OAuth server configuration.

DNS / Zone Setup

The auth.devprod.cloudflare.dev subdomain needs to be configured. The devprod.cloudflare.dev zone is already in use by other workers in this repo (e.g., playground.devprod.cloudflare.dev), so the zone should already be available.

WebSocket Client in Wrangler

Node.js has a global WebSocket available since v21. Since this project requires Node >= 20, we should verify availability and potentially use the ws npm package as a fallback or polyfill. Alternatively, we could use undici's WebSocket support.

---

Part 5: Future Work (not in scope for initial PR)

• Make WebSocket flow the default: Remove --x-websocket-callback flag, use WebSocket flow by default, keep --local-server as fallback for air-gapped environments.
• Rate limiting: Add rate limiting to the auth worker to prevent abuse.
• Monitoring: Add metrics/logging to the auth worker for operational visibility.

---

Reference

Current Wrangler Auth Flow

For context, the current wrangler login flow works as follows:

1. Wrangler generates PKCE codes (code_verifier + code_challenge) and a random state
2. Wrangler starts an HTTP server on localhost:8976
3. Wrangler constructs the auth URL pointing to dash.cloudflare.com/oauth2/auth with redirect_uri=http://localhost:8976/oauth/callback
4. Wrangler opens the browser to the auth URL
5. User authenticates in the browser
6. Cloudflare OAuth redirects browser to http://localhost:8976/oauth/callback?code=X&state=Y
7. Wrangler's local server validates state, exchanges code for tokens using code_verifier
8. Local server sends 307 redirect to welcome.developers.workers.dev/wrangler-oauth-consent-granted
9. Wrangler stores tokens in ~/.wrangler/config/default.toml

Key files in the current implementation:

File	Purpose
packages/wrangler/src/user/user.ts	Core OAuth implementation (~1450 lines)
packages/wrangler/src/user/commands.ts	CLI command definitions
packages/wrangler/src/user/auth-variables.ts	OAuth endpoint URLs, client IDs
packages/wrangler/src/user/generate-auth-url.ts	Auth URL builder, OAUTH_CALLBACK_URL constant
packages/wrangler/src/user/generate-random-state.ts	CSRF state parameter generator

Prior Art: OpenCode OAuth Patterns

OpenCode (Anthropic's CLI for Claude) faces the same OAuth challenge — authenticating users from terminal environments where localhost may not be accessible. It uses two complementary strategies across its provider and MCP server authentication.

Device Authorization Flow (no localhost required)

For GitHub Copilot and OpenAI Codex "headless" mode, OpenCode avoids the localhost problem entirely by using the Device Authorization Flow (RFC 8628):

1. CLI posts to the provider's device code endpoint to get a device_code + user_code
2. User visits a verification URL in any browser (no redirect back to localhost)
3. CLI polls the token endpoint until the user completes authorization
4. Handles slow_down responses per RFC 8628 §3.5 by increasing the poll interval

This works in containers, remote VMs, and Codespaces because the browser never needs to redirect back to the CLI — the CLI polls for completion instead.

Provider	Device Code Endpoint	Token Endpoint	Client ID
GitHub Copilot	https://github.com/login/device/code	https://github.com/login/oauth/access_token	Ov23li8tweQw6odWQebz
OpenAI Codex (headless)	https://auth.openai.com/api/accounts/deviceauth/start	https://auth.openai.com/oauth/token	app_EMoamEEZ73f0CkXaXp7hrann

Tradeoff vs. WebSocket relay: Device flow requires no server infrastructure but depends on the OAuth provider supporting it. Cloudflare's OAuth server does not currently support device flow, which is why this design uses the WebSocket relay approach instead.

Local Callback Server Patterns

When device flow isn't available, OpenCode uses local HTTP callback servers — similar to Wrangler's current approach:

Use Case	Port	Callback Path	Timeout
OpenAI Codex (browser)	1455	/auth/callback	—
MCP Server OAuth	19876	/mcp/oauth/callback	5 min per pending auth

Both use PKCE (S256) and state parameter validation for security. The MCP callback server additionally supports multiple concurrent pending auths keyed by state, which allows parallel authentication to different MCP servers.

Relevant similarities to Wrangler's current flow:

• PKCE with S256 code challenge method (code_verifier never leaves the CLI)
• Cryptographic random state for CSRF protection
• State validated on callback before code exchange
• Auto-cleanup timeouts for stale sessions

Key difference: OpenCode does not currently have a relay mechanism for environments where localhost is inaccessible. For MCP servers, the fallback is that the user must configure an API token manually. This is the gap the WebSocket relay design addresses for Wrangler.

OAuth 2.0 Device Authorization Grant approach

The OAuth 2.0 Device Authorization Grant (often just called the "Device Flow") is an authentication method designed specifically for devices that have an internet connection but either lack a web browser or have very limited input capabilities. Think of Smart TVs, game consoles, CLI (command-line interface) tools, or IoT devices where typing out a complex password with a remote control is a frustrating experience.

Instead of forcing the user to log in directly on the device, the Device Flow offloads the authentication to a secondary device, like a smartphone or a laptop.

How It Works

The process involves three main actors: the Device (the smart TV or CLI), the Authorization Server (the identity provider, like Google or Okta), and the User (with their smartphone or laptop).

1. The Device Requests Authorization When the user wants to log in, the device sends a request to the Authorization Server's device endpoint. It asks for permission to start the login process.

2. The Authorization Server Responds with Codes The server responds to the device with a few critical pieces of information:

• device_code: A long, secure string that the device keeps secret to identify its request.
• user_code: A short, easy-to-type string (e.g., ABCD-1234).
• verification_uri: A URL for the user to visit (e.g., login.example.com/device).
• expires_in: How long these codes are valid (usually 10–15 minutes).
• interval: How often the device is allowed to poll the server for an update.

3. The Device Prompts the User The device displays a message to the user: "Please go to login.example.com/device on your phone and enter the code ABCD-1234."

4. The User Authenticates (On a Secondary Device) The user pulls out their smartphone, navigates to the URL, and enters the user_code. They are then prompted to log into their account normally (using passwords, biometrics, 2FA, etc.) and explicitly grant the device access to their account.

5. The Device Polls for a Token (Background Process) While the user is fumbling with their phone in Step 4, the device is not just sitting idle. It continuously "polls" the Authorization Server's token endpoint in the background (e.g., every 5 seconds).

• It sends its secret device_code and asks: "Did the user authorize me yet?"
• The server replies: authorization_pending (meaning, "Not yet, keep waiting").

6. Access Granted Once the user finishes logging in and granting permission on their phone, the device's next polling request will finally succeed. The Authorization Server stops saying "pending" and instead returns an access_token (and optionally a refresh_token). The device uses this token to access the user's data, and the screen updates to show that the user is successfully logged in.