feat: add dynamic authorization support via callback provider by EddieHouston · Pull Request #194 · bitcoindevkit/rust-electrum-client

EddieHouston · 2026-01-16T12:13:54Z

Description

This PR adds support for dynamic authorization in Electrum RPC requests.
This enables authentication with authorization-protected Electrum servers and API gateways.

Use cases:

Bearer token authentication (JWT, OAuth, API keys)
API gateways requiring authorization headers
Any dynamic authorization scenario where tokens need to be updated during the client's lifetime

Notes to the reviewers

The implementation uses a callback pattern rather than a static token to support dynamic scenarios like automatic token refresh. The AuthProvider is called for each RPC request, allowing the token to be updated without reconnecting the client.

Both Config and RawClient structs needed custom Debug implementations since function pointers don't implement Debug - this is handled by displaying <provider> when an auth provider is present, which prevents leaking sensitive token values in debug output.

Thread safety is ensured through Arc wrapping and Send + Sync bounds, making this safe for concurrent use across the client.

Tests added:
14 new tests, all passing

Changelog notice

Added: Dynamic authorization support via AuthProvider callback in ConfigBuilder. Enables authentication with authorization-protected Electrum servers and automatic token refresh patterns for Bearer tokens, API keys, and other authorization schemes.

Checklists

All Submissions:

I followed the contribution guidelines

New Features:

I've added tests for the new feature
I've added docs for the new feature

Bugfixes:

This pull request breaks the existing API
I've added tests to reproduce the issue which are now passing
I'm linking the issue being fixed by this PR

notmandatory · 2026-01-21T14:53:31Z

concept ACK

Thanks for this, adding an "authorization" header is the most common way to authenticate to a http endpoints so this should be generally useful. Appreciate the comprehensive examples and unit tests.

The team is spread a bit thin so it may take some time to get it reviewed and tested.

oleonardolima

cACK

I did an initial round of review. Overall, it looks good! I'll give it a try testing it.

luisschwab · 2026-02-13T19:11:21Z

@EddieHouston needs rebase

EddieHouston · 2026-02-19T10:28:24Z

@EddieHouston needs rebase

@oleonardolima Was this still planned to release before the Electrum protocol v1.6 changes?

oleonardolima · 2026-02-19T19:10:24Z

@EddieHouston needs rebase

@oleonardolima Was this still planned to release before the Electrum protocol v1.6 changes?

I'm planning to have both under the same release, as the version negotiation is should work fine for new v1.6 and old servers. Appreciate it, if you could do a rebase.

oleonardolima · 2026-02-19T19:17:25Z

Also, you could use the opportunity to squash into a single commit, as it touches the same files.

EddieHouston · 2026-02-20T09:57:57Z

@EddieHouston needs rebase

@oleonardolima Was this still planned to release before the Electrum protocol v1.6 changes?

I'm planning to have both under the same release, as the version negotiation is should work fine for new v1.6 and old servers. Appreciate it, if you could do a rebase.

Looks like changes for electrum protocol v1.6 break this. The new negotiate_protocol_version are automatically called from constructors... those need to now pass auth as well so the call to server.version can succeed.
Update coming soon

EddieHouston · 2026-02-20T10:17:30Z

@EddieHouston needs rebase

@oleonardolima Was this still planned to release before the Electrum protocol v1.6 changes?

I'm planning to have both under the same release, as the version negotiation is should work fine for new v1.6 and old servers. Appreciate it, if you could do a rebase.

Looks like changes for electrum protocol v1.6 break this. The new negotiate_protocol_version are automatically called from constructors... those need to now pass auth as well so the call to server.version can succeed. Update coming soon

I asked Claude Code to fix this issue (squashed the change and force pushed):

Here's the old flow:

RawClient::new_ssl(url, validate_domain, timeout) // 1. creates stream
// 2. negotiate_protocol_version() ← sends server.version WITHOUT auth
// 3. returns client
.with_auth_provider(config.auth_provider()) // 4. sets auth ← TOO LATE

The electrum server requiring auth also requires auth on server.version, so step 2 fails before we ever get to step 4.

The _with_auth constructors fix the ordering:

RawClient::new_ssl_with_auth(url, validate_domain, timeout, auth_provider)
// 1. creates stream
// 2. client.auth_provider = auth_provider ← auth set FIRST
// 3. negotiate_protocol_version() ← sends server.version WITH auth ✓

Tested locally and this works.

oleonardolima · 2026-02-20T17:12:56Z

I asked Claude Code to fix this issue (squashed the change and force pushed):

Here's the old flow:

RawClient::new_ssl(url, validate_domain, timeout) // 1. creates stream // 2. negotiate_protocol_version() ← sends server.version WITHOUT auth // 3. returns client .with_auth_provider(config.auth_provider()) // 4. sets auth ← TOO LATE

The electrum server requiring auth also requires auth on server.version, so step 2 fails before we ever get to step 4.

The _with_auth constructors fix the ordering:

RawClient::new_ssl_with_auth(url, validate_domain, timeout, auth_provider) // 1. creates stream // 2. client.auth_provider = auth_provider ← auth set FIRST // 3. negotiate_protocol_version() ← sends server.version WITH auth ✓

Tested locally and this works.

@EddieHouston It looks like Claude didn't fully fixed the issues, CI is failing.

oleonardolima · 2026-02-20T18:00:22Z

I asked Claude Code to fix this issue (squashed the change and force pushed):
Here's the old flow:
RawClient::new_ssl(url, validate_domain, timeout) // 1. creates stream // 2. negotiate_protocol_version() ← sends server.version WITHOUT auth // 3. returns client .with_auth_provider(config.auth_provider()) // 4. sets auth ← TOO LATE
The electrum server requiring auth also requires auth on server.version, so step 2 fails before we ever get to step 4.
The _with_auth constructors fix the ordering:
RawClient::new_ssl_with_auth(url, validate_domain, timeout, auth_provider) // 1. creates stream // 2. client.auth_provider = auth_provider ← auth set FIRST // 3. negotiate_protocol_version() ← sends server.version WITH auth ✓
Tested locally and this works.

@EddieHouston It looks like Claude didn't fully fixed the issues, CI is failing.

I asked it to fix it, and it gave this suggestions, see: 17fc5b6

Oh, still failing though 🤦

EddieHouston · 2026-02-23T10:13:13Z

I asked Claude Code to fix this issue (squashed the change and force pushed):
Here's the old flow:
RawClient::new_ssl(url, validate_domain, timeout) // 1. creates stream // 2. negotiate_protocol_version() ← sends server.version WITHOUT auth // 3. returns client .with_auth_provider(config.auth_provider()) // 4. sets auth ← TOO LATE
The electrum server requiring auth also requires auth on server.version, so step 2 fails before we ever get to step 4.
The _with_auth constructors fix the ordering:
RawClient::new_ssl_with_auth(url, validate_domain, timeout, auth_provider) // 1. creates stream // 2. client.auth_provider = auth_provider ← auth set FIRST // 3. negotiate_protocol_version() ← sends server.version WITH auth ✓
Tested locally and this works.

@EddieHouston It looks like Claude didn't fully fixed the issues, CI is failing.

The CI runs with --no-default-features --features proxy (no SSL).
The new_proxy_ssl_with_auth method references ElectrumSslStream but is missing the #[cfg] gate that the public new_proxy_ssl has.

@oleonardolima Updated with fix. Ran the cargo check --no-default-features --features proxy locally and see it works now.

EddieHouston · 2026-02-23T17:45:28Z

@oleonardolima I'll ran these locally and resolved the issues:
cargo clippy --all-features --all-targets -- -D warnings
cargo fmt --all -- --config format_code_in_doc_comments=true --check
cargo test --verbose --all-features

Newbee question... Is there an easy way to run all the CI test locally?

EddieHouston · 2026-02-23T17:52:42Z

@oleonardolima I'll ran these locally and resolved the issues: cargo clippy --all-features --all-targets -- -D warnings cargo fmt --all -- --config format_code_in_doc_comments=true --check cargo test --verbose --all-features

Newbee question... Is there an easy way to run all the CI test locally?
Figured it out...

1. fmt

cargo fmt --all -- --config format_code_in_doc_comments=true --check

2. clippy

cargo clippy --all-features --all-targets -- -D warnings

3. tests

cargo test --verbose --all-features

4. check all feature combinations

cargo check --verbose --features default
cargo check --verbose --no-default-features
cargo check --verbose --no-default-features --features proxy
cargo check --verbose --no-default-features --features openssl
cargo check --verbose --no-default-features --features rustls
cargo check --verbose --no-default-features --features rustls-ring
cargo check --verbose --no-default-features --features proxy,openssl,rustls,rustls-ring

5.

rustup toolchain install 1.75.0
cargo +1.75.0 check --verbose --all-features

oleonardolima

utACK 09345de

It looks good, though I'm wondering what's the rationale on adding new methods, instead of update the existing ones APIs. Did you want to reduce the number of breaking changes ?

I'll come up with a patch with some changes I have in mind, to see if the API would be better.

oleonardolima · 2026-02-23T20:32:20Z

src/types.rs

+    #[test]
+    fn test_authorization_field_omitted_when_none() {
+        let req = Request::new_id(1, "test.method", vec![]);
+
+        let json = serde_json::to_string(&req).unwrap();
+
+        // The JSON should not contain the word "authorization" at all
+        assert!(!json.contains("authorization"));
+    }


nit: can't you could just move this assertion to the first test ?

oleonardolima · 2026-02-23T20:39:43Z

src/raw_client.rs

    /// The protocol version negotiated with the server via `server.version`.
    protocol_version: Mutex<Option<String>>,

+    auth_provider: Option<AuthProvider>,


nit: could use documentation

oleonardolima · 2026-02-23T20:48:24Z

src/raw_client.rs

    /// This sends `server.version` as the first message and stores the negotiated
    /// protocol version. Called automatically by constructors.
-    fn negotiate_protocol_version(&self) -> Result<(), Error> {
+    pub(crate) fn negotiate_protocol_version(&self) -> Result<(), Error> {


question: what's the rationale on making this pub(crate) ? I didn't see any new usage of it.

EddieHouston mentioned this pull request Jan 16, 2026

feat(electrum): add custom authentication support via ConfigBuilder bitcoindevkit/bdk#2096

Closed

6 tasks

EddieHouston force-pushed the rpc-auth branch 2 times, most recently from 7e9324b to db94491 Compare January 19, 2026 16:27

oleonardolima assigned EddieHouston Jan 19, 2026

oleonardolima self-requested a review January 19, 2026 17:05

notmandatory added the new feature New feature or request label Jan 19, 2026

oleonardolima added this to BDK Chain Jan 19, 2026

oleonardolima moved this to Discussion in BDK Chain Jan 19, 2026

oleonardolima reviewed Jan 26, 2026

View reviewed changes

oleonardolima mentioned this pull request Jan 26, 2026

Feature parity with electrum_client bitcoindevkit/electrum_streaming_client#9

Open

oleonardolima mentioned this pull request Feb 9, 2026

Implement Electrum Protocol v1.6 #190

Merged

oleonardolima moved this from Discussion to Needs Review in BDK Chain Feb 10, 2026

oleonardolima added the api API breaking change label Feb 10, 2026

oleonardolima requested review from luisschwab and oleonardolima February 10, 2026 14:00

oleonardolima mentioned this pull request Feb 10, 2026

chore(release): electrum-client 0.25.0 #197

Open

7 tasks

oleonardolima mentioned this pull request Feb 19, 2026

feat: add authorization support bitcoindevkit/electrum_streaming_client#14

Open

EddieHouston force-pushed the rpc-auth branch from db94491 to 3781f4d Compare February 20, 2026 09:56

EddieHouston force-pushed the rpc-auth branch from 3781f4d to ca27c4a Compare February 20, 2026 10:14

EddieHouston force-pushed the rpc-auth branch from ca27c4a to 3590cea Compare February 23, 2026 10:13

feat: add dynamic JWT authorization support via callback provider

09345de

EddieHouston force-pushed the rpc-auth branch from 3590cea to 09345de Compare February 23, 2026 17:45

oleonardolima reviewed Feb 23, 2026

View reviewed changes

Comments

Conversation

EddieHouston commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Notes to the reviewers

Changelog notice

Checklists

All Submissions:

New Features:

Bugfixes:

Uh oh!

notmandatory commented Jan 21, 2026

Uh oh!

oleonardolima left a comment

Choose a reason for hiding this comment

Uh oh!

luisschwab commented Feb 13, 2026

Uh oh!

EddieHouston commented Feb 19, 2026

Uh oh!

oleonardolima commented Feb 19, 2026

Uh oh!

oleonardolima commented Feb 19, 2026

Uh oh!

EddieHouston commented Feb 20, 2026

Uh oh!

EddieHouston commented Feb 20, 2026

Uh oh!

oleonardolima commented Feb 20, 2026

Uh oh!

oleonardolima commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

EddieHouston commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

EddieHouston commented Feb 23, 2026

Uh oh!

EddieHouston commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

1. fmt

2. clippy

3. tests

4. check all feature combinations

5.

Uh oh!

oleonardolima left a comment

Choose a reason for hiding this comment

Uh oh!

oleonardolima Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

oleonardolima Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

oleonardolima Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

EddieHouston commented Jan 16, 2026 •

edited

Loading

oleonardolima commented Feb 20, 2026 •

edited

Loading

EddieHouston commented Feb 23, 2026 •

edited

Loading

EddieHouston commented Feb 23, 2026 •

edited

Loading