WebSocket (and probably fetch) does not support Authorization header from URL

[domenic]

Bug Description

When I create a connection to a WebSocket URL such as ws://foo:bar@localhost:1337/, no Authorization header shows up.

Reproducible By

const { WebSocket } = require("undici");
const { createServer } = require("http");

const server = createServer();
server.on("upgrade", (req) => {
  console.log("Authorization:", req.headers.authorization);
  console.log("Expected:     ", "Basic " + Buffer.from("foo:bar").toString("base64"));
  process.exit();
});

server.listen(0, () => {
  new WebSocket(`ws://foo:bar@localhost:${server.address().port}/`);
});

Expected Behavior

The header should be available.

Web platform test: https://github.com/web-platform-tests/wpt/blob/master/websockets/basic-auth.any.js

Logs & Screenshots

Authorization: undefined
Expected:      Basic Zm9vOmJhcg==

Environment

• Node v25.2.1
• undici 7.18.2

Additional context

Claude claims this is caused by

undici/lib/web/fetch/index.js

Lines 1527 to 1534 in 250efc8

	// 20. If includeCredentials is true, then:
	if (includeCredentials) {
	// 1. If the user agent is not configured to block cookies for httpRequest
	// (see section 7 of [COOKIES]), then:
	// TODO: credentials
	// 2. If httpRequest’s header list does not contain `Authorization`, then:
	// TODO: credentials
	}

, and that seems plausible, although I haven't double-checked that the fetch code is used for the WebSocket connection.

The ws package gets this correct: https://github.com/websockets/ws/blob/ca533a53f338c4a40a3881dd6dff7e5867d06893/lib/websocket.js#L848-L856

[mcollina]

Regarding fetch.

The Fetch specification requires this at Step 13.3 of the Request constructor:

"If parsedURL includes credentials, throw a TypeError."

This is documented at https://fetch.spec.whatwg.org/#dom-request

The undici code implements this exactly at
lib/web/fetch/request.js:139-145:

// 3. If parsedURL includes credentials, then throw a TypeError. if (parsedURL.username || parsedURL.password) { throw new TypeError( 'Request cannot be constructed from a URL that includes credentials: ' + input ) }

[mcollina]

#4745 implements the WebSocket support. One more wpt passing!

[KhafraDev]

Claude claims this is caused by

Claude is (partially...) correct!

[KhafraDev]

undici seems to be handling this correctly. isAuthenticationFetch is only set in step 14.4 of https://fetch.spec.whatwg.org/#http-network-or-cache-fetch where traversable for user prompts is always no-traversable since it's not set by the WebSocket request.

isAuthenticationFetch is therefore always false and credentials are never set. Both Firefox and Chrome have the same behavior.

[domenic]

Unsure why @KhafraDev is closing this despite it not being fixed until #4745 is merged, but, I'm glad to see that @mcollina is on the case!

[domenic]

undici seems to be handling this correctly. isAuthenticationFetch is only set in step 14.4 of https://fetch.spec.whatwg.org/#http-network-or-cache-fetch where traversable for user prompts is always no-traversable since it's not set by the WebSocket request.

Step 14.4 is only after a 401 is received. This bug report is about what headers the server receives before it sends any status code. The relevant step is 8.21.2.

[KhafraDev]

It's not a bug, from what I can tell. The only time isAuthenticationFetch is set to true (which it is required to be in 8.21.2) is when receiving a 401 and some other conditions (8.14.4).

I then tested on both Chrome and Firefox and both had the same behavior as undici.

It's completely possible I missed something or misunderstand something, but an authentication entry isn't ever set in the fetch or websocket spec, and the websocket spec never sets the use-URL-credentials flag either.

e: an authentication entry can be set in http-network-or-cache-fetch if isAuthenticationFetch is true

If isAuthenticationFetch is true, then create an authentication entry for request and the given realm.

[domenic]

Stepping back, Chrome and Firefox (and Safari) pass this test; see wpt.fyi, wpt.live.

Note the use-URL-credentials flag is not require to be set to use the username:password from the URL. That flag only controls whether the URL credentials override the credentials store. If there is no credential store (which is the case in undici), then the URL credentials will always be used.

But yes, I do think there might be a spec bug here, where the spec doesn't match browser behavior. I'll file one on Fetch.

[domenic]

I believe the bug is that the WebSockets standard should set use-URL-credentials to true. (Like XMLHttpRequest, but unlike fetch().) With that fix, here is the per-spec flow that makes browsers pass:

Start from HTTP-network-or-cache fetch with isAuthenticationFetch set to false, i.e., the initial request to the server.

• Do we add an Authorization header? (Step 8.21)
  • Step 8.21.2: "If there’s an authentication entry for httpRequest" is false.
  • Step 8.21.3: "isAuthenticationFetch is true" is false.
  • So, no Authorization header on this initial request. (As expected.)
• We get back the 401 in step 14. Note that "request’s traversable for user prompts is a traversable navigable" is true, because in browsers these requests are made in the context of a browser tab.
  • request's use-URL-credentials flag is set, so we skip 14.3. This means it wasn't actually important whether we were in the context of a browser tab or not.
  • We go to 14.4 and reenter HTTP-network-or-cache fetch with isAuthenticationFetch set to true.

On our second pass through HTTP-network-or-cache fetch with isAuthenticationFetch set to true:

• Step 8.21.2: "If there’s an authentication entry for httpRequest" is false.
• Step 8.21.3: "if httpRequest’s current URL does include credentials and isAuthenticationFetch is true" is true, so we add the Authorization header from the URL.