docs(transport): document the TLS trust hook

Author: jamesarich

README.md

@@ -332,6 +332,42 @@ val config = MqttConfig(
 
 Log levels from most to least verbose: `TRACE` → `DEBUG` → `INFO` → `WARN` → `ERROR` → `NONE`.
 
+### Custom TLS trust
+
+By default the TCP transport validates the broker certificate against the platform CA store. To
+reach a broker behind a private or self-signed CA, pass a TLS customisation lambda to
+`TcpTransportFactory`. It runs against ktor's `TLSConfigBuilder`:
+
+```kotlin
+import org.meshtastic.mqtt.transport.tcp.TcpTransportFactory
+
+val client = MqttClient("my-client") {
+    transportFactory = TcpTransportFactory { trustManager = myPrivateCaTrustManager }
+}
+client.connect(MqttEndpoint.parse("mqtts://broker.internal:8883"))
+```
+
+The hook is applied after the SNI server name is resolved and before platform trust is configured.
+On Android that ordering matters: your trust manager is *wrapped* by the hostname-aware trust
+manager rather than replacing it, so certificate hostname verification still happens.
+
+This scopes the extra trust to the MQTT connection alone. It replaces the app-wide workaround of
+adding `<certificates src="user"/>` to `network_security_config.xml`, which would affect every
+HTTPS connection the app makes.
+
+The hook composes with transport selection as usual:
+
+```kotlin
+transportFactory = TcpTransportFactory { trustManager = myPrivateCaTrustManager } +
+    WebSocketTransportFactory()
+```
+
+`TLSConfigBuilder` comes from `io.ktor:ktor-network-tls`, exposed transitively by
+`mqtt-client-transport-tcp` — no extra dependency needed. The WebSocket transport has no equivalent
+hook yet. `trustManager` specifically is available on the JVM and Android actuals of
+`TLSConfigBuilder`; on Apple, Linux, and Windows targets the hook still runs, but `TLSConfigBuilder`
+exposes a different set of properties there.
+
 ## Android / KMP Integration
 
 The library is designed as a drop-in MQTT client for KMP projects. Consumer ProGuard/R8 rules are bundled automatically.

transport-tcp/Module.md

@@ -12,5 +12,23 @@ val client = MqttClient("sensor") {
 client.connect(MqttEndpoint.Tcp("broker.example.com", port = 8883, tls = true))
 ```
 
+### Trusting a private CA
+
+If the broker's certificate is issued by a private or self-signed CA that is not in the platform
+trust store, pass a TLS customisation lambda. It receives ktor's `TLSConfigBuilder`:
+
+```kotlin
+val client = MqttClient("sensor") {
+    transportFactory = TcpTransportFactory { trustManager = myTrustManager }
+}
+```
+
+The lambda is applied after the SNI server name is set and before platform trust configuration, so
+on Android a trust manager installed here is still wrapped in the hostname-aware delegate rather
+than replacing it. The added trust applies only to this MQTT connection — unlike Android's
+app-wide `network_security_config.xml` trust anchors. `trustManager` itself is available on the
+JVM and Android actuals of `TLSConfigBuilder`; on Apple, Linux, and Windows the lambda still runs,
+but `TLSConfigBuilder` exposes a different set of properties there.
+
 Available on JVM, Android, iOS, macOS, Linux, and Windows. Not available on the browser (wasmJs) —
 use `mqtt-client-transport-ws` there.