fix(transport): restore no-arg klib ctors, narrow trust docs

Addresses PR #103 review feedback.

- Add explicit `constructor() : this(null)` to TcpTransport and
  TcpTransportFactory. The klib dump now carries `constructor <init>()`
  alongside the Function1 overload, so the native ABI change is additive
  rather than a replacement. The JVM dump is unchanged — no signature
  clash with the constructor Kotlin already synthesises for an
  all-defaults primary constructor. This contradicts the PR body's claim
  that the klib replacement was inherent and unfixable; it was not.

- Narrow the platform-trust claim in PlatformTls.kt, TcpTransport.kt,
  README.md, and Module.md. Installing a trust manager REPLACES the
  platform's trust decision; network_security_config anchors, pinning,
  and CT policy then hold only insofar as that manager enforces them,
  and apply as before only when trustManager is left unset. The wrapping
  preserves the hostname-aware call path, not the platform's policy.
  X509TrustManagerExtensions also accepts any manager declaring the
  three-arg checkServerTrusted reflectively, so "must come from
  TrustManagerFactory" was too strong.

- Module.md heading h3 -> h2; four-backtick outer fences in the plan doc
  so nested Kotlin fences stop terminating the block early.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: jamesarich

README.md

@@ -348,23 +348,30 @@ 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 your trust anchors remain subject to the platform's
-domain-specific `network_security_config.xml` rules, certificate pinning, and Certificate
-Transparency policy instead of replacing that policy wholesale.
-
-Be clear about what the wrapping does *not* buy you. Android's hostname-aware
-`checkServerTrusted(chain, authType, hostname)` uses the hostname to look up that policy — it does
-not perform RFC 6125 subject-name matching. That check comes from ktor and only runs when the SNI
+On Android that ordering means your trust manager is reached through the hostname-aware
+`checkServerTrusted(chain, authType, hostname)` overload, which the platform requires whenever
+`network_security_config.xml` holds any domain-specific configuration — rather than being discarded
+in favour of the platform wrapper.
+
+Be clear about what that does *not* buy you. Installing your own trust manager **replaces the
+platform's trust decision**: your anchors are used instead of the platform's, and
+`network_security_config.xml` anchors, certificate pinning, and Certificate Transparency policy are
+then enforced only insofar as your manager enforces them itself. Those platform policies apply as
+before only if you leave `trustManager` unset. The wrapping preserves the hostname-aware *call
+path*, not the platform's *policy*.
+
+RFC 6125 subject-name matching is separate again. Android's 3-arg overload uses the hostname for
+policy lookup, not for subject-name matching; that check comes from ktor and only runs when the SNI
 server name is set, so it is absent for IP-literal brokers such as `mqtts://192.168.1.50:8883`. On
-JVM and native targets there is no platform trust wrapping at all, so ktor's SNI-gated
-subject-name check is the only peer-identity verification beyond chain validation. If your trust
-manager accepts any chain, nothing else will stop a mismatched certificate.
-
-On Android the trust manager you install must be one the platform can wrap: obtain it from a
-`TrustManagerFactory` initialised with a `KeyStore` containing your CA, rather than hand-writing an
-`X509TrustManager`. A hand-written one that implements only the two-arg `checkServerTrusted` cannot
-be wrapped and the handshake fails with an `IllegalArgumentException` explaining this.
+JVM and native targets there is no platform trust wrapping at all, so ktor's SNI-gated subject-name
+check is the only peer-identity verification beyond chain validation. If your trust manager accepts
+any chain, nothing else will stop a mismatched certificate.
+
+On Android the manager must be one `X509TrustManagerExtensions` can wrap: either obtained from a
+`TrustManagerFactory` initialised with a `KeyStore` containing your CA, or declaring the three-arg
+`checkServerTrusted(chain, authType, host)` that the platform looks up reflectively. A hand-written
+`X509TrustManager` implementing only the two-arg overload cannot be wrapped, and the handshake fails
+with an `IllegalArgumentException` explaining this.
 
 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

docs/superpowers/plans/2026-07-25-tls-trust-hook.md

@@ -571,7 +571,7 @@ Document the hook where a consumer hitting the issue #102 problem will actually
 In `transport-tcp/Module.md`, insert between the existing code fence (ends line 13) and the
 "Available on JVM, Android, …" paragraph (line 15):
 
-```markdown
+````markdown
 ### Trusting a private CA
 
 If the broker's certificate is issued by a private or self-signed CA that is not in the platform
@@ -587,14 +587,14 @@ The lambda is applied after the SNI server name is set and before platform trust
 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.
-```
+````
 
 - [ ] **Step 2: Add the README section**
 
 In `README.md`, insert immediately before line 335 (`## Android / KMP Integration`), after the
 "Log levels from most to least verbose…" line that closes the Logging section:
 
-```markdown
+````markdown
 ### Custom TLS trust
 
 By default the TCP transport validates the broker certificate against the platform CA store. To
@@ -611,8 +611,10 @@ 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.
+On Android that ordering means your trust manager is reached through the hostname-aware
+`checkServerTrusted(chain, authType, hostname)` overload rather than being discarded. Note that
+installing your own trust manager replaces the platform's trust decision — see the shipped
+`README.md` section for the full statement of what that does and does not preserve.
 
 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
@@ -628,7 +630,7 @@ transportFactory = TcpTransportFactory { trustManager = myPrivateCaTrustManager
 `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.
-```
+````
 
 - [ ] **Step 3: Verify the docs build**
 

transport-tcp/Module.md

@@ -12,7 +12,7 @@ val client = MqttClient("sensor") {
 client.connect(MqttEndpoint.Tcp("broker.example.com", port = 8883, tls = true))
 ```
 
-### Trusting a private CA
+## 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`:
@@ -23,18 +23,29 @@ val client = MqttClient("sensor") {
 }
 ```
 
-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 wrapped in the hostname-aware delegate rather than
-replacing it: the trust anchors you add stay subject to the platform's domain-specific
-`network_security_config.xml` rules, certificate pinning, and Certificate Transparency policy. That
-is all the wrapping buys — RFC 6125 subject-name matching comes from ktor and only when the SNI
-server name is set, so it does not happen for IP-literal brokers, and the platform policy checks do
-not happen at all on JVM or native targets. On Android the trust manager must be one the platform
-can wrap (obtained from a `TrustManagerFactory`, not hand-implemented) or the handshake fails.
-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.
+The lambda is applied after the SNI server name is set and before platform trust configuration. On
+Android that ordering means the trust manager on the builder is reached through the hostname-aware
+`checkServerTrusted(chain, authType, hostname)` overload, which the platform requires whenever
+`network_security_config.xml` holds any domain-specific configuration.
+
+Be precise about what that does *not* buy you. Installing your own trust manager **replaces the
+platform's trust decision**: your anchors are used instead of the platform's, and
+`network_security_config.xml` anchors, certificate pinning, and Certificate Transparency policy are
+then enforced only insofar as your manager enforces them itself. Those platform policies apply as
+before only if you leave `trustManager` unset. Wrapping preserves the hostname-aware *call path*,
+not the platform's *policy*. RFC 6125 subject-name matching is separate again — it comes from ktor
+and only when the SNI server name is set, so it does not happen for IP-literal brokers, and no
+platform wrapping happens at all on JVM or native targets.
+
+On Android the manager must be one `X509TrustManagerExtensions` can wrap: either obtained from a
+`TrustManagerFactory`, or declaring the three-arg `checkServerTrusted(chain, authType, host)` that
+the platform looks up reflectively. Otherwise the handshake fails with an `IllegalArgumentException`
+explaining this.
+
+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.

transport-tcp/api/transport-tcp.klib.api

@@ -7,6 +7,7 @@
 
 // Library unique name: <MQTTastic-Client-KMP:transport-tcp>
 final class org.meshtastic.mqtt.transport.tcp/TcpTransport : org.meshtastic.mqtt/MqttTransport { // org.meshtastic.mqtt.transport.tcp/TcpTransport|null[0]
+    constructor <init>() // org.meshtastic.mqtt.transport.tcp/TcpTransport.<init>|<init>(){}[0]
     constructor <init>(kotlin/Function1<io.ktor.network.tls/TLSConfigBuilder, kotlin/Unit>? = ...) // org.meshtastic.mqtt.transport.tcp/TcpTransport.<init>|<init>(kotlin.Function1<io.ktor.network.tls.TLSConfigBuilder,kotlin.Unit>?){}[0]
 
     final val isConnected // org.meshtastic.mqtt.transport.tcp/TcpTransport.isConnected|{}isConnected[0]
@@ -19,6 +20,7 @@ final class org.meshtastic.mqtt.transport.tcp/TcpTransport : org.meshtastic.mqtt
 }
 
 final class org.meshtastic.mqtt.transport.tcp/TcpTransportFactory : org.meshtastic.mqtt/MqttTransportFactory { // org.meshtastic.mqtt.transport.tcp/TcpTransportFactory|null[0]
+    constructor <init>() // org.meshtastic.mqtt.transport.tcp/TcpTransportFactory.<init>|<init>(){}[0]
     constructor <init>(kotlin/Function1<io.ktor.network.tls/TLSConfigBuilder, kotlin/Unit>? = ...) // org.meshtastic.mqtt.transport.tcp/TcpTransportFactory.<init>|<init>(kotlin.Function1<io.ktor.network.tls.TLSConfigBuilder,kotlin.Unit>?){}[0]
 
     final fun create(org.meshtastic.mqtt/MqttEndpoint): org.meshtastic.mqtt/MqttTransport // org.meshtastic.mqtt.transport.tcp/TcpTransportFactory.create|create(org.meshtastic.mqtt.MqttEndpoint){}[0]

transport-tcp/src/commonMain/kotlin/org/meshtastic/mqtt/transport/tcp/PlatformTls.kt

@@ -48,18 +48,26 @@ internal expect fun TLSConfigBuilder.configurePlatformTrust(host: String)
  * 3. [configurePlatformTrust] — reads whatever trust manager is now on the builder and,
  *    on Android, wraps it in a hostname-aware delegate.
  *
- * Step 2 must precede step 3. Reversing them would let a caller-supplied trust manager
- * *replace* Android's `HostnameAwareTrustManager`, so the caller's trust anchors would no
- * longer be evaluated against the platform's domain-specific `network_security_config.xml`
- * rules, certificate pinning, or Certificate Transparency policy. Running the caller first
- * composes instead: a private-CA trust manager stays subject to those platform checks.
+ * Step 2 must precede step 3. What step 3 provides is the call path: whatever trust manager is
+ * on the builder is reached through Android's hostname-aware
+ * `checkServerTrusted(chain, authType, hostname)` overload, which `NetworkSecurityTrustManager`
+ * requires whenever `network_security_config.xml` holds any domain-specific configuration.
+ * Reversing the two steps would discard that wrapper, leaving ktor's 2-arg call to hit the bare
+ * manager.
  *
- * Note what this ordering does *not* provide. RFC 6125 subject-name matching (verifying the
- * certificate actually names the host being contacted) comes from ktor, which performs it only
- * when `serverName` is non-`null` — so it is absent for IP-literal brokers. Android's 3-arg
- * `checkServerTrusted(chain, authType, hostname)` uses the hostname for config lookup, pinning,
- * and CT policy, not for subject-name matching. On JVM and native targets
- * [configurePlatformTrust] is a no-op, so no platform policy check happens there at all.
+ * Be precise about what this ordering does *not* provide. Installing a trust manager via
+ * [configureTls] *replaces the platform's trust decision*: that manager's anchors are used
+ * instead of the platform's, and `network_security_config.xml` anchors, certificate pinning,
+ * and Certificate Transparency policy are then enforced only insofar as that manager enforces
+ * them itself. Those platform policies apply as they did before only when the caller leaves
+ * `trustManager` unset. Wrapping preserves the hostname-aware *call path*, not the platform's
+ * *policy*.
+ *
+ * RFC 6125 subject-name matching (verifying the certificate actually names the host being
+ * contacted) is separate again: it comes from ktor, which performs it only when `serverName` is
+ * non-`null` — so it is absent for IP-literal brokers. Android's 3-arg overload uses the
+ * hostname for config lookup, pinning, and CT policy, not for subject-name matching. On JVM and
+ * native targets [configurePlatformTrust] is a no-op, so no platform wrapping happens at all.
  *
  * The hook may read or replace `serverName`, but setting it to `null` disables ktor's
  * subject-name verification entirely — the only name matching this transport has on JVM and

transport-tcp/src/commonMain/kotlin/org/meshtastic/mqtt/transport/tcp/TcpTransport.kt

@@ -58,6 +58,8 @@ import org.meshtastic.mqtt.packet.VariableByteInt
 public class TcpTransport(
     internal val configureTls: (TLSConfigBuilder.() -> Unit)? = null,
 ) : MqttTransport {
+    public constructor() : this(null)
+
     private var socket: Socket? = null
     private var selectorManager: SelectorManager? = null
     private var readChannel: ByteReadChannel? = null
@@ -279,14 +281,18 @@ internal fun isIpLiteral(host: String): Boolean {
  *
  * @param configureTls optional hook applied to ktor's [TLSConfigBuilder] for every transport
  *   this factory creates. It runs after the SNI server name is set and before platform trust
- *   is configured, so on Android a trust manager installed here is wrapped in the
- *   hostname-aware delegate rather than replacing it — the caller's trust anchors stay subject
- *   to the platform's network-security-config, pinning, and Certificate Transparency policy.
- *   That wrapping is Android-only and is not subject-name matching; see [applyMqttTls].
+ *   is configured, so on Android a trust manager installed here is reached through the
+ *   hostname-aware `checkServerTrusted` overload rather than bypassing it. Note that installing
+ *   a trust manager replaces the platform's trust decision — network-security-config anchors,
+ *   pinning, and Certificate Transparency policy then hold only insofar as that manager enforces
+ *   them. The wrapping is Android-only and is not subject-name matching; see [applyMqttTls] for
+ *   the full picture before relying on it.
  */
 public class TcpTransportFactory(
     private val configureTls: (TLSConfigBuilder.() -> Unit)? = null,
 ) : MqttTransportFactory {
+    public constructor() : this(null)
+
     override fun supports(endpoint: MqttEndpoint): Boolean = endpoint is MqttEndpoint.Tcp
 
     override fun create(endpoint: MqttEndpoint): MqttTransport = TcpTransport(configureTls)