feat: add Bearer token authentication support

[w1am]

Adds Bearer token authentication to the Rust client. Until now requests could only carry HTTP Basic credentials. This PR adds a parallel path so callers can send Authorization: Bearer <token> for OAuth/OIDC flows. The bridge work in DEV-1644 depends on it.

The change is fully additive: nothing existing breaks, no migrations needed.

What's new

• Authentication enum with Basic(Credentials) and Bearer(Bytes) variants.
• Authentication::basic(login, password) and Authentication::bearer(token) constructors.
• impl From<Credentials> for Authentication so the existing API surface relaxes without breaking callers.
• build_request_metadata and http_configure_auth now match on the variant and emit the right Authorization header.

How to use it

use kurrentdb::{Authentication, AppendToStreamOptions};

let opts = AppendToStreamOptions::default()
    .authenticated(Authentication::bearer("eyJ..."));

If you're already using Credentials::new(...), nothing changes:

options.authenticated(Credentials::new("admin", "changeit")); // still works

Backward compatibility

Note

No existing code needs to change. Credentials, its constructor, connection-string parsing, and the TOML/JSON serde format for credentials are all unchanged.

.authenticated() was relaxed from (Credentials) to (impl Into<Authentication>). Calls passing a Credentials value continue to compile because of the new From impl. Per cargo's semver rules this counts as a minor change.

---

Closes DEV-1643.
Required by DEV-1644.

[linear]

DEV-1643 Add Bearer token authentication support to KurrentDB Rust client

[qodo-code-review]

Review Summary by Qodo

Add Bearer token authentication support to KurrentDB Rust client

✨ Enhancement

Walkthroughs

Description

• Add Authentication enum supporting Basic and Bearer token variants
• Implement Bearer token authentication for OAuth/OIDC integration
• Maintain backward compatibility with existing Credentials API
• Update HTTP and gRPC request metadata to handle both auth types
• Add comprehensive unit tests for auth header construction

Diagram

flowchart LR
  A["Authentication Enum<br/>Basic/Bearer"] --> B["build_authorization_header<br/>gRPC metadata"]
  A --> C["http_configure_auth<br/>HTTP requests"]
  D["Credentials"] --> A
  E[".authenticated() builder"] --> A
  B --> F["Authorization header<br/>Basic/Bearer format"]
  C --> F

Loading

File Changes

1. kurrentdb/src/types.rs ✨ Enhancement +40/-0

Add Authentication enum with Basic and Bearer variants

• Introduce Authentication enum with Basic(Credentials) and Bearer(Bytes) variants
• Add Authentication::basic() and Authentication::bearer() constructor methods
• Implement From<Credentials> for Authentication for backward compatibility

kurrentdb/src/types.rs

---

2. kurrentdb/src/request.rs ✨ Enhancement +143/-15

Update gRPC metadata to support Bearer authentication

• Refactor build_request_metadata() to handle Authentication enum instead of just Credentials
• Extract build_authorization_header() function to generate correct header format per auth type
• Add 9 comprehensive unit tests covering Basic/Bearer headers, special characters, conversion, and
 builder acceptance

kurrentdb/src/request.rs

---

3. kurrentdb/src/http/mod.rs ✨ Enhancement +22/-6

Update HTTP auth configuration for Bearer support

• Add resolve_authentication() helper to handle per-operation override and connection-string
 fallback
• Update http_configure_auth() to branch on Authentication variant and use basic_auth() or
 bearer_auth()
• Change parameter from Option<&Credentials> to Option<&Authentication>

kurrentdb/src/http/mod.rs

---

View more (5)

4. kurrentdb/src/http/persistent_subscriptions.rs ✨ Enhancement +10/-40

Refactor persistent subscriptions auth handling

• Replace inline auth resolution with calls to resolve_authentication() helper
• Update 5 call sites to use new helper function for cleaner code
• Maintain same authentication fallback logic (per-call override then connection-string default)

kurrentdb/src/http/persistent_subscriptions.rs

---

5. kurrentdb/src/operations/gossip.rs ✨ Enhancement +6/-1

Update gossip operation for Authentication enum

• Convert default user credentials to Authentication::Basic before passing to
 http_configure_auth()
• Update gossip HTTP read operation to work with new authentication type

kurrentdb/src/operations/gossip.rs

---

6. kurrentdb/src/options/mod.rs ✨ Enhancement +2/-2

Update CommonOperationOptions to use Authentication

• Replace credentials: Option<Credentials> with authentication: Option<Authentication> in
 CommonOperationOptions
• Update import from Credentials to Authentication

kurrentdb/src/options/mod.rs

---

7. eventstore-macros/src/lib.rs ✨ Enhancement +9/-3

Update authenticated builder macro for generic auth

• Update .authenticated() builder method to accept impl Into<Authentication> instead of just
 Credentials
• Update documentation to mention Bearer token support
• Store authentication in common_operation_options.authentication field

eventstore-macros/src/lib.rs

---

8. kurrentdb/Cargo.toml ⚙️ Configuration changes +1/-1

Bump version to 1.1.0

• Bump version from 1.0.0 to 1.1.0 (additive minor release)

kurrentdb/Cargo.toml

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

1. Bearer metadata can panic ☑ 🐞 Bug ☼ Reliability

Description

build_authorization_header formats Bearer tokens verbatim and then calls
MetadataValue::try_from(...).expect(...), which will panic if the resulting header contains
non-ASCII or other invalid metadata characters.

Code

kurrentdb/src/request.rs[R44-65]

+fn build_authorization_header(
+    auth: &Authentication,
+) -> tonic::metadata::MetadataValue<tonic::metadata::Ascii> {
+    use tonic::metadata::MetadataValue;
+
+    let header = match auth {
+        Authentication::Basic(Credentials { login, password }) => {
+            let login = String::from_utf8_lossy(login);
+            let password = String::from_utf8_lossy(password);
+            let encoded = base64::engine::general_purpose::STANDARD
+                .encode(format!("{}:{}", login, password));
+            format!("Basic {}", encoded)
+        }
+        Authentication::Bearer(token) => {
+            let token = String::from_utf8_lossy(token);
+            format!("Bearer {}", token)
+        }
+    };
+
+    MetadataValue::try_from(header.as_str())
+        .expect("Auth header value should be valid metadata header value")
+}

Evidence

The gRPC path builds a MetadataValue<Ascii> for the authorization header and uses expect(...) on
the conversion result. For Bearer, the token is inserted verbatim (after a lossy UTF-8 conversion),
so any non-ASCII characters (including U+FFFD produced by lossy conversion) or other invalid header
characters will cause try_from to return Err and the client will panic while constructing
request metadata.

kurrentdb/src/request.rs[44-65]
kurrentdb/src/types.rs[81-87]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`build_authorization_header` uses `MetadataValue::try_from(...).expect(...)`. With Bearer tokens being inserted verbatim, invalid header characters (notably any non-ASCII) will cause a panic when building gRPC request metadata.

### Issue Context
Bearer tokens are not base64-encoded by this client; they are sent as provided. Even if a caller passes valid UTF-8, non-ASCII characters are enough to make `MetadataValue<Ascii>` construction fail. Additionally, `String::from_utf8_lossy` can introduce U+FFFD, which is non-ASCII.

### Fix Focus Areas
- kurrentdb/src/request.rs[44-65]

### Suggested fix
- Replace `expect(...)` with non-panicking handling:
 - Option A (preferred): change `build_request_metadata` / `build_authorization_header` to return `crate::Result<MetadataMap>` and propagate an error up through `commands::new_request`.
 - Option B: return `Option<MetadataValue<Ascii>>` from `build_authorization_header` and only insert the header when conversion succeeds, while emitting a structured error log (without logging the token).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Unchecked UTF-8 in HTTP auth ☑ 🐞 Bug ⛨ Security

Description

http_configure_auth uses std::str::from_utf8_unchecked on Credentials and Bearer token
Bytes, but Credentials::new / Authentication::bearer allow constructing these from arbitrary
bytes; invalid UTF-8 violates the unsafe precondition and can lead to undefined behavior.

Code

kurrentdb/src/http/mod.rs[R22-29]

+    match auth_opt {
+        Some(crate::Authentication::Basic(creds)) => builder.basic_auth(
            unsafe { std::str::from_utf8_unchecked(creds.login.as_ref()) },
            unsafe { Some(std::str::from_utf8_unchecked(creds.password.as_ref())) },
-        )
-    } else {
-        builder
+        ),
+        Some(crate::Authentication::Bearer(token)) => {
+            builder.bearer_auth(unsafe { std::str::from_utf8_unchecked(token.as_ref()) })
+        }

Evidence

http_configure_auth converts raw Bytes to &str with from_utf8_unchecked, which is only sound
if the bytes are valid UTF-8. The public constructors accept S: Into<Bytes> with no UTF-8
validation, so callers can provide non-UTF8 data and trigger UB when building HTTP requests.

kurrentdb/src/http/mod.rs[18-31]
kurrentdb/src/types.rs[43-54]
kurrentdb/src/types.rs[72-87]
Best Practice: Rust std::str::from_utf8_unchecked

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`http_configure_auth` uses `std::str::from_utf8_unchecked` on authentication bytes. Since `Credentials` and `Authentication::Bearer` can be constructed from arbitrary `Bytes`, this can invoke undefined behavior when bytes are not valid UTF-8.

### Issue Context
This is a public-facing API footgun: users can pass `Vec<u8>`, `Bytes`, or other non-UTF8 sources into `Credentials::new` / `Authentication::bearer`.

### Fix Focus Areas
- kurrentdb/src/http/mod.rs[18-31]
- kurrentdb/src/types.rs[43-54]
- kurrentdb/src/types.rs[72-87]

### Suggested fix
- Remove `from_utf8_unchecked` and use a safe conversion:
 - Prefer `std::str::from_utf8(...)` and handle `Err` (log + skip auth, or plumb an error), or
 - Use `String::from_utf8_lossy(...)` and pass the resulting `Cow<str>` into `basic_auth` / `bearer_auth` (both accept `Display`).
- Optionally: tighten the API by storing auth material as `String` (or a validated wrapper) instead of `Bytes`, if acceptable.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---