Add combined protocol auth helpers for tooling

Sources/Mailozaurr.Tests/ConnectorTests.cs

@@ -23,6 +23,7 @@ private class FakeImapClient : ImapClient
         public override bool IsAuthenticated => Authenticated;
         private bool _connected;
         private int _timeout;
+        public string? AuthMechanism { get; private set; }
         public override bool IsConnected => _connected;
         public override int Timeout { get => _timeout; set => _timeout = value; }
         public bool Disposed { get; private set; }
@@ -44,6 +45,11 @@ public override Task DisconnectAsync(bool quit, CancellationToken cancellationTo
             _connected = false;
             return Task.CompletedTask;
         }
+        public override Task AuthenticateAsync(SaslMechanism mechanism, CancellationToken cancellationToken = default) {
+            AuthMechanism = mechanism.GetType().Name;
+            Authenticated = true;
+            return Task.CompletedTask;
+        }
         protected override void Dispose(bool disposing)
         {
             Disposed = true;
@@ -160,6 +166,25 @@ public async Task ImapConnector_RequestOverload_UsesRequestSettings()
         Assert.Equal(4321, fake.Timeout);
     }
 
+    [Fact]
+    public async Task ImapConnector_ConnectAuthenticatedAsync_UsesOAuthAuthentication() {
+        var fake = new FakeImapClient();
+        ImapConnector.ClientFactory = () => fake;
+        var request = new ImapConnectionRequest("imap.example.test", 993);
+
+        var client = await ImapConnector.ConnectAuthenticatedAsync(
+            request,
+            userName: "user@example.com",
+            secret: "oauth-token",
+            mode: ProtocolAuthMode.OAuth2);
+
+        ImapConnector.ClientFactory = () => new ImapClient();
+
+        Assert.Same(fake, client);
+        Assert.True(fake.IsAuthenticated);
+        Assert.Equal(nameof(SaslMechanismOAuth2), fake.AuthMechanism);
+    }
+
     [Fact]
     public async Task ImapConnector_RequestOverload_ValidatesArguments()
     {

Sources/Mailozaurr.Tests/SmtpAsyncWrappersTests.cs

@@ -16,9 +16,24 @@ public class SmtpAsyncWrappersTests
     private class FakeConnectClient : ClientSmtp
     {
         public bool ConnectCalled;
+        public bool ThrowOnConnect;
+        public bool ThrowOnAuthenticate;
+        public SecureSocketOptions? LastSecureSocketOptions;
+        public string? AuthMechanism;
         public override Task ConnectAsync(string host, int port, SecureSocketOptions options, CancellationToken cancellationToken = default)
         {
+            if (ThrowOnConnect) {
+                throw new InvalidOperationException("connect failed");
+            }
             ConnectCalled = true;
+            LastSecureSocketOptions = options;
+            return Task.CompletedTask;
+        }
+        public override Task AuthenticateAsync(SaslMechanism mechanism, CancellationToken cancellationToken = default) {
+            if (ThrowOnAuthenticate) {
+                throw new InvalidOperationException("auth failed");
+            }
+            AuthMechanism = mechanism.GetType().Name;
             return Task.CompletedTask;
         }
     }
@@ -42,6 +57,65 @@ public async Task ConnectAsync_InvokesClientConnectAsync()
         Assert.True(result.Status);
     }
 
+    [Fact]
+    public async Task ConnectAndAuthenticateAsync_ReturnsSuccessForOAuthAuthentication()
+    {
+        var smtp = new Smtp();
+        var fake = new FakeConnectClient();
+        SetClient(smtp, fake);
+
+        var result = await smtp.ConnectAndAuthenticateAsync(
+            "host",
+            587,
+            "user@example.com",
+            "oauth-token",
+            SecureSocketOptions.StartTls,
+            useSsl: false,
+            authMode: ProtocolAuthMode.OAuth2);
+
+        Assert.True(result.IsSuccess);
+        Assert.Equal(SecureSocketOptions.StartTls, result.SecureSocketOptions);
+        Assert.Equal(nameof(SaslMechanismOAuth2), fake.AuthMechanism);
+    }
+
+    [Fact]
+    public async Task ConnectAndAuthenticateAsync_MapsConnectFailure()
+    {
+        var smtp = new Smtp();
+        var fake = new FakeConnectClient { ThrowOnConnect = true };
+        SetClient(smtp, fake);
+
+        var result = await smtp.ConnectAndAuthenticateAsync(
+            "host",
+            587,
+            "user@example.com",
+            "secret",
+            authMode: ProtocolAuthMode.OAuth2);
+
+        Assert.False(result.IsSuccess);
+        Assert.Equal("connect_failed", result.ErrorCode);
+        Assert.True(result.IsTransient);
+    }
+
+    [Fact]
+    public async Task ConnectAndAuthenticateAsync_MapsAuthenticationFailure()
+    {
+        var smtp = new Smtp();
+        var fake = new FakeConnectClient { ThrowOnAuthenticate = true };
+        SetClient(smtp, fake);
+
+        var result = await smtp.ConnectAndAuthenticateAsync(
+            "host",
+            587,
+            "user@example.com",
+            "secret",
+            authMode: ProtocolAuthMode.OAuth2);
+
+        Assert.False(result.IsSuccess);
+        Assert.Equal("auth_failed", result.ErrorCode);
+        Assert.False(result.IsTransient);
+    }
+
     [Fact]
     public async Task CreateMessageAsync_AutoEmbedImagesAddsInlineAttachment()
     {

Sources/Mailozaurr/Connections/ImapConnector.cs

@@ -94,4 +94,29 @@ public static Task<ImapClient> ConnectAsync(
             retryDelayBackoff,
             DelayAsync,
             cancellationToken);
+
+    /// <summary>
+    /// Connects and authenticates to an IMAP server using protocol auth settings in one step.
+    /// </summary>
+    /// <param name="request">Connection request settings.</param>
+    /// <param name="userName">IMAP user name.</param>
+    /// <param name="secret">IMAP password or OAuth token.</param>
+    /// <param name="mode">Authentication mode.</param>
+    /// <param name="cancellationToken">Token used to cancel the operation.</param>
+    /// <returns>Authenticated <see cref="ImapClient"/> instance.</returns>
+    public static Task<ImapClient> ConnectAuthenticatedAsync(
+        ImapConnectionRequest request,
+        string userName,
+        string secret,
+        ProtocolAuthMode mode = ProtocolAuthMode.Basic,
+        CancellationToken cancellationToken = default) {
+        if (request is null) {
+            throw new ArgumentNullException(nameof(request));
+        }
+
+        return ConnectAsync(
+            request,
+            (client, ct) => ProtocolAuth.AuthenticateImapAsync(client, userName, secret, mode, ct),
+            cancellationToken);
+    }
 }

Sources/Mailozaurr/Smtp/Smtp.cs

@@ -76,6 +76,11 @@ public string? PendingMessagesPath {
     /// <summary>Credentials used during authentication.</summary>
     public NetworkCredential? Credential { get; private set; }
 
+    /// <summary>
+    /// Effective secure socket options used by the active or most recent connection attempt.
+    /// </summary>
+    public SecureSocketOptions ActiveSecureSocketOptions => _activeSecureSocketOptions;
+
     /// <summary>
     /// Optional identity hint used to isolate SMTP connection pooling by credentials.
     /// </summary>
@@ -590,6 +595,58 @@ public async Task<SmtpResult> ConnectAsync(string server, int port, SecureSocket
         }
     }
 
+    /// <summary>
+    /// Connects and authenticates using the provided user name/secret in one step.
+    /// </summary>
+    /// <param name="server">SMTP server hostname.</param>
+    /// <param name="port">SMTP server port.</param>
+    /// <param name="userName">SMTP user name.</param>
+    /// <param name="secret">SMTP password or OAuth token.</param>
+    /// <param name="secureSocketOptions">TLS/SSL options.</param>
+    /// <param name="useSsl">Compatibility SSL switch.</param>
+    /// <param name="authMode">Authentication mode.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Combined connect/auth outcome.</returns>
+    public async Task<SmtpConnectAuthenticateResult> ConnectAndAuthenticateAsync(
+        string server,
+        int port,
+        string userName,
+        string secret,
+        SecureSocketOptions secureSocketOptions = SecureSocketOptions.Auto,
+        bool useSsl = false,
+        ProtocolAuthMode authMode = ProtocolAuthMode.Basic,
+        CancellationToken cancellationToken = default) {
+        var connectResult = await ConnectAsync(server, port, secureSocketOptions, useSsl).ConfigureAwait(false);
+        if (!connectResult.Status) {
+            return new SmtpConnectAuthenticateResult {
+                IsSuccess = false,
+                SecureSocketOptions = ActiveSecureSocketOptions,
+                ErrorCode = "connect_failed",
+                Error = connectResult.Error ?? "Connect failed.",
+                IsTransient = true
+            };
+        }
+
+        try {
+            await ProtocolAuth.AuthenticateSmtpAsync(Client, userName, secret, authMode, cancellationToken).ConfigureAwait(false);
+            Credential = new NetworkCredential(userName?.Trim() ?? string.Empty, secret ?? string.Empty);
+            return new SmtpConnectAuthenticateResult {
+                IsSuccess = true,
+                SecureSocketOptions = ActiveSecureSocketOptions
+            };
+        } catch (OperationCanceledException) {
+            throw;
+        } catch (Exception ex) {
+            return new SmtpConnectAuthenticateResult {
+                IsSuccess = false,
+                SecureSocketOptions = ActiveSecureSocketOptions,
+                ErrorCode = "auth_failed",
+                Error = ex.Message,
+                IsTransient = false
+            };
+        }
+    }
+
     /// <summary>
     /// Authenticate using the provided credentials.
     /// </summary>

Sources/Mailozaurr/Smtp/SmtpConnectAuthenticateResult.cs

@@ -0,0 +1,33 @@
+using MailKit.Security;
+
+namespace Mailozaurr;
+
+/// <summary>
+/// Result of connecting and authenticating an SMTP session.
+/// </summary>
+public sealed class SmtpConnectAuthenticateResult {
+    /// <summary>
+    /// True when both connect and authenticate succeeded.
+    /// </summary>
+    public bool IsSuccess { get; init; }
+
+    /// <summary>
+    /// Effective secure socket options used for the connection.
+    /// </summary>
+    public SecureSocketOptions SecureSocketOptions { get; init; } = SecureSocketOptions.Auto;
+
+    /// <summary>
+    /// Stable error code for connect/auth failures.
+    /// </summary>
+    public string ErrorCode { get; init; } = string.Empty;
+
+    /// <summary>
+    /// Human-readable error text.
+    /// </summary>
+    public string Error { get; init; } = string.Empty;
+
+    /// <summary>
+    /// True when the failure is likely transient.
+    /// </summary>
+    public bool IsTransient { get; init; }
+}