From 3bda04124e30cb2f055c1e4acd82c568acbc4ddd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jonas=20Sch=C3=A4fer?= <jonas@zombofant.net>
Date: Wed, 12 Nov 2025 12:07:32 +0100
Subject: [PATCH] tokio-xmpp: publish auth method

---
 tokio-xmpp/ChangeLog           | 3 +++
 tokio-xmpp/src/client/login.rs | 5 +++++
 tokio-xmpp/src/client/mod.rs   | 1 +
 tokio-xmpp/src/lib.rs          | 2 +-
 4 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/tokio-xmpp/ChangeLog b/tokio-xmpp/ChangeLog
index 507d4065..b870cbae 100644
--- a/tokio-xmpp/ChangeLog
+++ b/tokio-xmpp/ChangeLog
@@ -1,5 +1,8 @@
 Version NEXT:
 0000-00-00 RELEASER <releaser@domain>
+    * Added:
+      - Expose `client_auth` method to allow manual stream setups for advanced
+        use cases.
     * Fixed:
       - Ignore missing "version" stream attribute for 0114 components.
       - Gate `AsRawFd` behind `ktls` feature to make Windows build work again.
diff --git a/tokio-xmpp/src/client/login.rs b/tokio-xmpp/src/client/login.rs
index 0f72c6ec..0ff67743 100644
--- a/tokio-xmpp/src/client/login.rs
+++ b/tokio-xmpp/src/client/login.rs
@@ -23,6 +23,11 @@ use crate::{
     },
 };
 
+/// Run the authentication handshake on a given stream.
+///
+/// Uses the given `sasl_mechanisms` and `creds` to perform the full
+/// authentication handshake. As authentication ends with a stream reset,
+/// this returns the `stream` as [`InitiatingStream`] on success.
 pub async fn auth<S: AsyncBufRead + AsyncWrite + Unpin>(
     mut stream: XmppStream<S>,
     sasl_mechanisms: &SaslMechanisms,
diff --git a/tokio-xmpp/src/client/mod.rs b/tokio-xmpp/src/client/mod.rs
index 18922a34..dd687e77 100644
--- a/tokio-xmpp/src/client/mod.rs
+++ b/tokio-xmpp/src/client/mod.rs
@@ -28,6 +28,7 @@ use crate::connect::TcpServerConnector;
 mod iq;
 pub(crate) mod login;
 mod stream;
+pub use login::auth;
 
 pub use iq::{IqFailure, IqRequest, IqResponse, IqResponseToken};
 
diff --git a/tokio-xmpp/src/lib.rs b/tokio-xmpp/src/lib.rs
index 9242008f..2fa684b4 100644
--- a/tokio-xmpp/src/lib.rs
+++ b/tokio-xmpp/src/lib.rs
@@ -128,7 +128,7 @@ pub use xso::{asxml::PrintRawXml, error::FromElementError};
 #[doc(inline)]
 /// Generic tokio_xmpp Error
 pub use crate::error::Error;
-pub use client::{Client, IqFailure, IqRequest, IqResponse, IqResponseToken};
+pub use client::{auth as client_login, Client, IqFailure, IqRequest, IqResponse, IqResponseToken};
 #[cfg(feature = "insecure-tcp")]
 pub use component::Component;
 pub use event::{Event, Stanza};