📝 zb: Add security documentation and warnings to system methods

Closes dbus2#1275 by adding basic and sufficient, but attention-grabbing, documentation
to all `system*` methods in the crate which either are or utilize the result of
zbus::Address::system to describe their security properties.

I took the approach to centralize the details/important parts on
zbus::Address::system and then use interdoc links to redirect all of the
other "affected" callsites there to reduce duplication.

Author: complexspaces

zbus/src/address/mod.rs

@@ -87,6 +87,17 @@ impl Address {
     /// Get the address for the system bus respecting the `DBUS_SYSTEM_BUS_ADDRESS` environment
     /// variable. If we don't recognize the value (or it's not set) we fall back to
     /// `/var/run/dbus/system_bus_socket`.
+    ///
+    /// # Security
+    ///
+    /// <div class="warning">
+    ///
+    /// `zbus` does not perform any security checks or trust validation on the address (path)
+    /// returned by this method.
+    ///
+    /// Users in security-sensitive contexts (ex: authentication) are responsible for validating
+    /// if the address is truly controlled by the system and trustworthy for the intended purpose.
+    /// </div>
     pub fn system() -> Result<Self> {
         match env::var("DBUS_SYSTEM_BUS_ADDRESS") {
             Ok(val) => Self::from_str(&val),

zbus/src/blocking/connection/builder.rs

@@ -30,6 +30,14 @@ impl<'a> Builder<'a> {
     }
 
     /// Create a builder for the system-wide message bus connection.
+    ///
+    /// # Security
+    ///
+    /// <div class="warning">
+    ///
+    /// `zbus` does not validate the address used by this builder's connection.
+    /// See [zbus::Address::system] for more details.
+    /// </div>
     pub fn system() -> Result<Self> {
         crate::connection::Builder::system().map(Self)
     }

zbus/src/blocking/connection/mod.rs

@@ -33,6 +33,14 @@ impl Connection {
     }
 
     /// Create a `Connection` to the system-wide message bus.
+    ///
+    /// # Security
+    ///
+    /// <div class="warning">
+    ///
+    /// `zbus` does not validate the address used by this connection.
+    /// See [zbus::Address::system] for more details.
+    /// </div>
     pub fn system() -> Result<Self> {
         block_on(crate::Connection::system()).map(Self::from)
     }

zbus/src/connection/builder.rs

@@ -78,6 +78,14 @@ impl<'a> Builder<'a> {
     }
 
     /// Create a builder for the system-wide message bus connection.
+    ///
+    /// # Security
+    ///
+    /// <div class="warning">
+    ///
+    /// `zbus` does not validate the address used by this builder's connection.
+    /// See [zbus::Address::system] for more details.
+    /// </div>
     pub fn system() -> Result<Self> {
         Ok(Self::new(Target::Address(Address::system()?)))
     }

zbus/src/connection/mod.rs

@@ -1193,6 +1193,14 @@ impl Connection {
     }
 
     /// Create a `Connection` to the system-wide message bus.
+    ///
+    /// # Security
+    ///
+    /// <div class="warning">
+    ///
+    /// `zbus` does not validate the address used by this connection.
+    /// See [zbus::Address::system] for more details.
+    /// </div>
     pub async fn system() -> Result<Self> {
         Builder::system()?.build().await
     }