feat!: add dynamic authorization support 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.

examples/JWT_AUTH_EXAMPLE.md

oleonardolima

tACK 020f193

It's looking good! I still think the API feels a bit odd, and we could just update the existing methods to have a new auth parameter, though it can be addressed in a follow-up (maybe in another release even).

I gave it a shot and tested it with non-authenticated (testnet) servers that support v1.6 by syncing/broadcasting w/ bdk_wallet, it's still working as expected.

I also tested it with authenticated (mainnet) servers, but didn't tested it by syncing/broadcasting w/ bdk_wallet, still need to test it in testnet/signet if possible.

src/config.rs

src/raw_client.rs

luisschwab

These should be removed, since electrum-client is unaware of bdk_electrum. This is a dependency loop.

examples/jwt_auth.rs

luisschwab · 2026-03-10T21:54:41Z

I still think the API feels a bit odd, and we could just update the existing methods to have a new auth parameter, though it can be addressed in a follow-up (maybe in another release even).

@EddieHouston how hard would it be run this in regtest on CI? Since we'll probably move some stuff around for the next release, would be nice to be able to test it out there and catch any regressions.

luisschwab · 2026-03-10T21:59:48Z

@EddieHouston can you also provide complete instructions on testing this with your servers?

oleonardolima · 2026-03-10T23:15:50Z

@EddieHouston can you also provide complete instructions on testing this with your servers?

@luisschwab You can probably start from this: oleonardolima@4f6bc16

I think that having it as a full example is better than have it all in just docs, will update to the latest changes and probably push that commit, wdyt @EddieHouston

luisschwab · 2026-03-10T23:17:33Z

@oleonardolima go ahead. While you're at it, can you squash the last 3 commits and fix formatting?

EddieHouston · 2026-03-11T06:08:21Z

I still think the API feels a bit odd, and we could just update the existing methods to have a new auth parameter, though it can be addressed in a follow-up (maybe in another release even).

@EddieHouston how hard would it be run this in regtest on CI? Since we'll probably move some stuff around for the next release, would be nice to be able to test it out there and catch any regressions.

In theory not difficult, just time. You could maybe mock up a test server that takes an API key or something.

oleonardolima · 2026-03-12T00:36:05Z

I cherry-picked my changes for the examples and squashed everything into a single commit.

I changed the jwt_dynamic_auth example to use bitreq instead of reqwest, as reqwest was bringing a bunch of MSRV issues on CI.

Adding a regtest auth infra for testing in CI can be done in a follow-up.

oleonardolima

tACK 1c7ad73

I've tested using this version of the electrum-client for FullScan/Sync and broadcasting with a bdk_wallet on Testnet3. I did it for both unauthenticated and authenticated servers, and it's working as expected.

evanlinjin

Thanks for this work. This is only a partial review.

src/config.rs

evanlinjin · 2026-03-13T14:21:47Z

src/raw_client.rs

                params.to_vec(),
            );
+
+            // Servers expect auth token only in the first request in batched requests


Unfortunately this library doesn't actually use JSON-RPC batch arrays - the "batch" here just means "write all in one go".

We need to add auth token to all requests.

@EddieHouston Are there any issues on the server side if we choose to send the authorization within every request ?

Anyway, I fixed this in 72dc88a

@EddieHouston Are there any issues on the server side if we choose to send the authorization within every request ?

yeah, it's a huge amount of extra unneeded data over the wire.

@EddieHouston Are there any issues on the server side if we choose to send the authorization within every request ?

yeah, it's a huge amount of extra unneeded data over the wire.

Oh, got it. However, we should probably follow with above's suggestion to guarantee general compatibility.

I don't see the problem, the original code adds the auth only on the first request in the batch, even though its using newline-delimited JSON-RPC, they are all flushed to the wire together and it has auth only on the first one as expected.

I think we can keep as it's for now, if leads to any performance issues we can change it and release in a patch release, as it'd be internal and non-breaking.

evanlinjin · 2026-03-13T14:25:45Z

src/types.rs

    pub params: Vec<Param>,
+    /// Optional authorization token (e.g., JWT Bearer token)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub authorization: Option<String>,


Is this intentionally made public? RawClient seems to overwrite this regardless (raw_client.rs:973).

Either make this pub(crate), or change logic to not override a caller-set value (however, does this feature even make sense?).

If I got it right, RawClient overwrites it because Request is always being created with an authorization as None.

Yes, it probably can be pub(crate) and already assigned when creating a new Request, that would also fix the issue of only adding the authorization to the first one in batch scenarios.

I fixed this in 72dc88a

Actually I changed it to private in the latest changes, there's no need to be either pub or pub(crate), you should set it through the new .with_auth() method.

evanlinjin · 2026-03-13T14:31:39Z

src/raw_client.rs

+        Self::new_with_auth(socket_addrs, timeout, None)
+    }
+
+    pub(crate) fn new_with_auth<A: ToSocketAddrs>(


All of the new .._with_auth methods seem to only populate the auto_provider field. Is this correct?

Instead of having all these duplicate methods - we can use a builder pattern by introducing a single method:

pub(crate) with_auth(mut self, auth_provider: AuthProvider) -> Self { self.auth_provider = Some(auth_provider); self }

I think this goes back to my previous comment.

Yes, we should give it a try to builder pattern, it'll give us a better API.
cc @EddieHouston

Alright, I did it in the latest commits. It now has a better API and follows the builder pattern.

outdated

- add new `AuthProvider` public type to handle an `authorization` token. - add new `Option<AuthProvider>` as `authorization_provider` in `Config`, it holds the dynamic authentication token callback provider. - add new `Option<AuthProvider>` as `auth_provider` in `RawClient`, it holds the dynamic authentication token callback provider. - add new `authorization` private field in `Request`. - add new `pub fn with_auth()` to `RawClient` in order to set the authorization provider into the client, it should be used following a builder patter, the client defaults to no authentication otherwise. - add new `.with_auth()` method to `Request`, it sets the `authorization` token, if any. - update `pub fn negotiate_protocol_version()` in `RawClient` to return the `RawClient`, this way it SHOULD no be used following a builder pattern. - update `.call()` and `.batch_call()` to use the newly added `.with_auth()`, instead of updating request's authorization field directly. BREAKING CHANGE: all changes above are API breaking changes.

- add two new examples: `jwt_auth.rs` and `jwt_dynamic_auth.rs` as references on how to build a client with authentication.

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

This comment was marked as outdated.

Sign in to view

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

This comment was marked as outdated.

Sign in to view

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

luisschwab requested changes Feb 24, 2026

View reviewed changes

examples/JWT_AUTH_EXAMPLE.md Outdated Show resolved Hide resolved

EddieHouston force-pushed the rpc-auth branch from 3e58253 to 020f193 Compare February 24, 2026 18:02

luisschwab requested a review from oleonardolima February 24, 2026 18:08

oleonardolima reviewed Mar 6, 2026

View reviewed changes

oleonardolima requested a review from luisschwab March 6, 2026 00:17

luisschwab requested changes Mar 10, 2026

View reviewed changes

src/config.rs Show resolved Hide resolved

src/raw_client.rs Outdated Show resolved Hide resolved

src/raw_client.rs Outdated Show resolved Hide resolved

luisschwab previously requested changes Mar 10, 2026

View reviewed changes

examples/jwt_auth.rs Outdated Show resolved Hide resolved

examples/jwt_auth.rs Outdated Show resolved Hide resolved

EddieHouston requested a review from luisschwab March 10, 2026 18:38

oleonardolima self-requested a review March 11, 2026 23:40

oleonardolima force-pushed the rpc-auth branch from 8d11b28 to 1c7ad73 Compare March 12, 2026 00:31

oleonardolima approved these changes Mar 12, 2026

View reviewed changes

evanlinjin previously requested changes Mar 13, 2026

View reviewed changes

oleonardolima force-pushed the rpc-auth branch from 1c7ad73 to 72dc88a Compare March 16, 2026 16:03

oleonardolima mentioned this pull request Mar 18, 2026

test: add integration tests for authorization-based electrum servers #199

Open

oleonardolima force-pushed the rpc-auth branch from 72dc88a to 6ff7044 Compare March 20, 2026 18:05

oleonardolima requested a review from evanlinjin March 20, 2026 18:08

oleonardolima requested review from notmandatory and oleonardolima March 20, 2026 18:08

EddieHouston and others added 2 commits March 20, 2026 15:11

docs: add references on how to use authentication

3df3814

- add two new examples: `jwt_auth.rs` and `jwt_dynamic_auth.rs` as references on how to build a client with authentication.

oleonardolima force-pushed the rpc-auth branch from 6ff7044 to 3df3814 Compare March 20, 2026 18:14

oleonardolima changed the title ~~feat: add dynamic authorization support via callback provider~~ feat!: add dynamic authorization support Mar 20, 2026

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!

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

Uh oh!

oleonardolima left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

luisschwab left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

luisschwab commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

luisschwab commented Mar 10, 2026

Uh oh!

oleonardolima commented Mar 10, 2026

Uh oh!

luisschwab commented Mar 10, 2026

Uh oh!

EddieHouston commented Mar 11, 2026

Uh oh!

oleonardolima commented Mar 12, 2026

Uh oh!

oleonardolima left a comment

Choose a reason for hiding this comment

Uh oh!

evanlinjin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

EddieHouston commented Jan 16, 2026 •

edited

Loading

luisschwab left a comment •

edited

Loading

luisschwab commented Mar 10, 2026 •

edited

Loading

oleonardolima Mar 16, 2026 •

edited

Loading