feat(auth): add MQTT username/password authentication support

Author: Jan VL

include/sparkplug/host_application.hpp

@@ -84,6 +84,8 @@ class HostApplication {
     bool clean_session = true;       ///< MQTT clean session flag
     int keep_alive_interval = 60;    ///< MQTT keep-alive interval in seconds (default: 60)
     std::optional<TlsOptions> tls{}; ///< TLS/SSL options (required if broker_url uses ssl://)
+    std::optional<std::string> username{}; ///< MQTT username for authentication (optional)
+    std::optional<std::string> password{}; ///< MQTT password for authentication (optional)
   };
 
   /**
@@ -106,6 +108,16 @@ class HostApplication {
   HostApplication(HostApplication&&) noexcept;
   HostApplication& operator=(HostApplication&&) noexcept;
 
+  /**
+   * @brief Sets MQTT username and password for authentication.
+   *
+   * @param username MQTT username (empty string or std::nullopt to unset)
+   * @param password MQTT password (empty string or std::nullopt to unset)
+   *
+   * @note Must be called before connect().
+   */
+  void set_credentials(std::optional<std::string> username, std::optional<std::string> password);
+
   /**
    * @brief Connects to the MQTT broker.
    *

include/sparkplug/publisher.hpp

@@ -111,7 +111,9 @@ class Publisher {
     int death_qos = 1;            ///< MQTT QoS for NDEATH Will Message. Sparkplug requires 1.
     bool clean_session = true;    ///< MQTT clean session flag
     int keep_alive_interval = 60; ///< MQTT keep-alive interval in seconds (Sparkplug recommends 60)
-    std::optional<TlsOptions> tls{}; ///< TLS/SSL options (required if broker_url uses ssl://)
+    std::optional<TlsOptions> tls{};       ///< TLS/SSL options (required if broker_url uses ssl://)
+    std::optional<std::string> username{}; ///< MQTT username for authentication (optional)
+    std::optional<std::string> password{}; ///< MQTT password for authentication (optional)
     std::optional<CommandCallback>
         command_callback{}; ///< Optional callback for NCMD messages (subscribed before NBIRTH)
   };
@@ -136,6 +138,16 @@ class Publisher {
   Publisher(Publisher&&) noexcept;
   Publisher& operator=(Publisher&&) noexcept;
 
+  /**
+   * @brief Sets MQTT username and password for authentication.
+   *
+   * @param username MQTT username (empty string or std::nullopt to unset)
+   * @param password MQTT password (empty string or std::nullopt to unset)
+   *
+   * @note Must be called before connect().
+   */
+  void set_credentials(std::optional<std::string> username, std::optional<std::string> password);
+
   /**
    * @brief Connects to the MQTT broker and establishes a Sparkplug B session.
    *

include/sparkplug/sparkplug_c.h

@@ -146,6 +146,19 @@ sparkplug_publisher_t* sparkplug_publisher_create(const char* broker_url, const
  */
 void sparkplug_publisher_destroy(sparkplug_publisher_t* pub);
 
+/**
+ * @brief Sets MQTT username and password for authentication.
+ *
+ * @param pub Publisher handle
+ * @param username MQTT username (may be NULL to unset)
+ * @param password MQTT password (may be NULL to unset)
+ * @return 0 on success, -1 on failure
+ *
+ * @note Must be called before sparkplug_publisher_connect().
+ */
+int sparkplug_publisher_set_credentials(sparkplug_publisher_t* pub, const char* username,
+                                        const char* password);
+
 /**
  * @brief Connects the publisher to the MQTT broker.
  *
@@ -386,6 +399,19 @@ sparkplug_host_application_t* sparkplug_host_application_create(const char* brok
  */
 void sparkplug_host_application_destroy(sparkplug_host_application_t* host);
 
+/**
+ * @brief Sets MQTT username and password for authentication.
+ *
+ * @param host Host Application handle
+ * @param username MQTT username (may be NULL to unset)
+ * @param password MQTT password (may be NULL to unset)
+ * @return 0 on success, -1 on failure
+ *
+ * @note Must be called before sparkplug_host_application_connect().
+ */
+int sparkplug_host_application_set_credentials(sparkplug_host_application_t* host,
+                                               const char* username, const char* password);
+
 /**
  * @brief Connects the Host Application to the MQTT broker.
  *
@@ -500,6 +526,19 @@ sparkplug_subscriber_t* sparkplug_subscriber_create(const char* broker_url, cons
  */
 void sparkplug_subscriber_destroy(sparkplug_subscriber_t* sub);
 
+/**
+ * @brief Sets MQTT username and password for authentication.
+ *
+ * @param sub Subscriber handle
+ * @param username MQTT username (may be NULL to unset)
+ * @param password MQTT password (may be NULL to unset)
+ * @return 0 on success, -1 on failure
+ *
+ * @note Must be called before sparkplug_subscriber_connect().
+ */
+int sparkplug_subscriber_set_credentials(sparkplug_subscriber_t* sub, const char* username,
+                                         const char* password);
+
 /**
  * @brief Connects the subscriber to the MQTT broker.
  *

include/sparkplug/subscriber.hpp

@@ -170,7 +170,9 @@ class Subscriber {
     bool clean_session = true;       ///< MQTT clean session flag
     bool validate_sequence = true;   ///< Enable sequence number validation (detects packet loss)
     std::optional<TlsOptions> tls{}; ///< TLS/SSL options (required if broker_url uses ssl://)
-    LogCallback log_callback{};      ///< Optional callback for library log messages
+    std::optional<std::string> username{}; ///< MQTT username for authentication (optional)
+    std::optional<std::string> password{}; ///< MQTT password for authentication (optional)
+    LogCallback log_callback{};            ///< Optional callback for library log messages
   };
 
   /**
@@ -239,6 +241,16 @@ class Subscriber {
   Subscriber(Subscriber&&) noexcept;
   Subscriber& operator=(Subscriber&&) noexcept;
 
+  /**
+   * @brief Sets MQTT username and password for authentication.
+   *
+   * @param username MQTT username (empty string or std::nullopt to unset)
+   * @param password MQTT password (empty string or std::nullopt to unset)
+   *
+   * @note Must be called before connect().
+   */
+  void set_credentials(std::optional<std::string> username, std::optional<std::string> password);
+
   /**
    * @brief Connects to the MQTT broker.
    *

src/c_bindings.cpp

@@ -162,6 +162,18 @@ void sparkplug_publisher_destroy(sparkplug_publisher_t* pub) {
   delete pub;
 }
 
+int sparkplug_publisher_set_credentials(sparkplug_publisher_t* pub, const char* username,
+                                        const char* password) {
+  if (!pub) {
+    return -1;
+  }
+
+  std::optional<std::string> user = username ? std::optional<std::string>(username) : std::nullopt;
+  std::optional<std::string> pass = password ? std::optional<std::string>(password) : std::nullopt;
+  pub->impl.set_credentials(std::move(user), std::move(pass));
+  return 0;
+}
+
 int sparkplug_publisher_connect(sparkplug_publisher_t* pub) {
   if (!pub)
     return -1;
@@ -371,6 +383,18 @@ void sparkplug_subscriber_destroy(sparkplug_subscriber_t* sub) {
   delete sub;
 }
 
+int sparkplug_subscriber_set_credentials(sparkplug_subscriber_t* sub, const char* username,
+                                         const char* password) {
+  if (!sub || !sub->impl) {
+    return -1;
+  }
+
+  std::optional<std::string> user = username ? std::optional<std::string>(username) : std::nullopt;
+  std::optional<std::string> pass = password ? std::optional<std::string>(password) : std::nullopt;
+  sub->impl->set_credentials(std::move(user), std::move(pass));
+  return 0;
+}
+
 int sparkplug_subscriber_connect(sparkplug_subscriber_t* sub) {
   if (!sub || !sub->impl)
     return -1;
@@ -835,6 +859,18 @@ void sparkplug_host_application_destroy(sparkplug_host_application_t* host) {
   delete host;
 }
 
+int sparkplug_host_application_set_credentials(sparkplug_host_application_t* host,
+                                               const char* username, const char* password) {
+  if (!host) {
+    return -1;
+  }
+
+  std::optional<std::string> user = username ? std::optional<std::string>(username) : std::nullopt;
+  std::optional<std::string> pass = password ? std::optional<std::string>(password) : std::nullopt;
+  host->impl.set_credentials(std::move(user), std::move(pass));
+  return 0;
+}
+
 int sparkplug_host_application_connect(sparkplug_host_application_t* host) {
   if (!host) {
     return -1;

src/host_application.cpp

@@ -76,6 +76,13 @@ HostApplication& HostApplication::operator=(HostApplication&& other) noexcept {
   return *this;
 }
 
+void HostApplication::set_credentials(std::optional<std::string> username,
+                                      std::optional<std::string> password) {
+  std::lock_guard<std::mutex> lock(mutex_);
+  config_.username = std::move(username);
+  config_.password = std::move(password);
+}
+
 std::expected<void, std::string> HostApplication::connect() {
   std::lock_guard<std::mutex> lock(mutex_);
 
@@ -91,6 +98,14 @@ std::expected<void, std::string> HostApplication::connect() {
   conn_opts.keepAliveInterval = config_.keep_alive_interval;
   conn_opts.cleansession = config_.clean_session;
 
+  // Set credentials if provided
+  if (config_.username.has_value()) {
+    conn_opts.username = config_.username.value().c_str();
+  }
+  if (config_.password.has_value()) {
+    conn_opts.password = config_.password.value().c_str();
+  }
+
   MQTTAsync_SSLOptions ssl_opts = MQTTAsync_SSLOptions_initializer;
   if (config_.tls.has_value()) {
     const auto& tls = config_.tls.value();

src/publisher.cpp

@@ -146,6 +146,13 @@ Publisher& Publisher::operator=(Publisher&& other) noexcept {
   return *this;
 }
 
+void Publisher::set_credentials(std::optional<std::string> username,
+                                std::optional<std::string> password) {
+  std::lock_guard<std::mutex> lock(mutex_);
+  config_.username = std::move(username);
+  config_.password = std::move(password);
+}
+
 std::expected<void, std::string> Publisher::connect() {
   std::lock_guard<std::mutex> lock(mutex_);
 
@@ -166,6 +173,14 @@ std::expected<void, std::string> Publisher::connect() {
   conn_opts.keepAliveInterval = config_.keep_alive_interval;
   conn_opts.cleansession = config_.clean_session;
 
+  // Set credentials if provided
+  if (config_.username.has_value()) {
+    conn_opts.username = config_.username.value().c_str();
+  }
+  if (config_.password.has_value()) {
+    conn_opts.password = config_.password.value().c_str();
+  }
+
   // Setup TLS/SSL if configured
   MQTTAsync_SSLOptions ssl_opts = MQTTAsync_SSLOptions_initializer;
   if (config_.tls.has_value()) {

src/subscriber.cpp

@@ -337,6 +337,13 @@ static void on_connection_lost(void* context, char* cause) {
   }
 }
 
+void Subscriber::set_credentials(std::optional<std::string> username,
+                                 std::optional<std::string> password) {
+  std::lock_guard<std::mutex> lock(mutex_);
+  config_.username = std::move(username);
+  config_.password = std::move(password);
+}
+
 std::expected<void, std::string> Subscriber::connect() {
   std::lock_guard<std::mutex> lock(mutex_);
 
@@ -360,6 +367,14 @@ std::expected<void, std::string> Subscriber::connect() {
   conn_opts.keepAliveInterval = DEFAULT_KEEP_ALIVE_INTERVAL;
   conn_opts.cleansession = config_.clean_session;
 
+  // Set credentials if provided
+  if (config_.username.has_value()) {
+    conn_opts.username = config_.username.value().c_str();
+  }
+  if (config_.password.has_value()) {
+    conn_opts.password = config_.password.value().c_str();
+  }
+
   MQTTAsync_SSLOptions ssl_opts = MQTTAsync_SSLOptions_initializer;
   if (config_.tls.has_value()) {
     const auto& tls = config_.tls.value();