Expose the browser `fetch` credentials mode in `BrowserClient`

[mauriceraguseinit]

Summary

BrowserClient currently maps its withCredentials option to only two browser fetch credentials modes:

credentials: withCredentials ? 'include' : 'same-origin',

This makes it possible to use:

• include
• same-origin

However, the third valid fetch credentials mode, omit, is currently not configurable through the public BrowserClient API.

It would be useful if BrowserClient allowed callers to explicitly configure the credentials mode used for browser requests.

Use case

In some Flutter Web applications, requests must be sent without browser credentials, even for same-origin requests. This means cookies, client certificates, and HTTP authentication information should not be included by the browser.

The desired browser fetch configuration is:

credentials: 'omit',

At the moment, the only way to achieve this behavior with package:http appears to be forking or copying the BrowserClient implementation and changing the request initialization manually.

Current behavior

When withCredentials is false, BrowserClient uses:

credentials: 'same-origin',

When withCredentials is true, BrowserClient uses:

credentials: 'include',

There is no public API to select:

credentials: 'omit',

Expected behavior

BrowserClient should expose a way to configure all credentials modes supported by the browser fetch API:

• omit
• same-origin
• include

This would avoid the need for package forks when applications require requests to be sent without browser credentials.

Possible API

One possible approach would be to introduce an explicit credentials mode enum:

enum BrowserCredentialsMode {
  omit,
  sameOrigin,
  include,
}

And allow it to be configured on BrowserClient:

final client = BrowserClient(
  credentialsMode: BrowserCredentialsMode.omit,
);

For backward compatibility, the default could remain equivalent to the current behavior:

BrowserCredentialsMode.sameOrigin

The existing withCredentials API could either be kept as a convenience option or deprecated in favor of the more explicit credentials mode.

Why withCredentials is not expressive enough

The current boolean API can only represent two states:

false -> same-origin
true  -> include

But the browser supports three distinct credentials modes:

omit
same-origin
include

Therefore, a boolean does not fully represent the underlying browser behavior.

Workaround

The current workaround is to fork or copy BrowserClient and change the RequestInit configuration manually:

credentials: 'omit',

This works technically, but it is difficult to maintain because the fork has to track upstream changes in package:http.

Benefits

Adding this option would:

• expose the full browser fetch credentials behavior
• remove the need for forks for this use case
• make credentials handling explicit at the call site
• improve compatibility with applications that have strict cookie or authentication requirements
• keep the existing default behavior unchanged

Proposed outcome

Please consider adding support for configuring the browser fetch credentials mode in BrowserClient, including support for omit.