react-native-audio-browser 0.2.0-next.1 → 0.2.0-next.11

package/android/src/main/java/com/audiobrowser/player/Player.kt

@@ -168,13 +168,26 @@ class Player(internal val context: Context) {
         mediaSessionCallback.updateMediaSession(
           mediaSession,
           options.capabilities,
-          options.notificationButtons,
+          options.remoteButtonLayout,
           searchAvailable,
+          options.forwardJumpInterval,
+          options.backwardJumpInterval,
         )
       }
     }
   }
 
+  /**
+   * Drops a completed browser registration so [awaitBrowser] waits for the replacement instead of
+   * handing out the disposed browser. A [CompletableDeferred] completes once, so it would otherwise
+   * pin the first browser for the life of the process.
+   */
+  fun forgetBrowserRegistration() {
+    if (browserRegistered.isCompleted) {
+      browserRegistered = CompletableDeferred()
+    }
+  }
+
   /**
    * Suspends until the browser is registered, with a timeout.
    *
@@ -834,8 +847,8 @@ class Player(internal val context: Context) {
    * A restart from a terminal error begins a new load of the same track: fresh retry budgets and
    * unproven playback, so the user's tap yields a visible first-connect retry window instead of a
    * single silent attempt — the same behavior as re-selecting the track (ADR 0004). Hooked off the
-   * player error clearing: every recovery path (retry(), play(), the transport controls'
-   * idle-error recovery) goes through exoPlayer.prepare(), which clears the error.
+   * player error clearing: every recovery path (retry(), play(), the transport controls' idle-error
+   * recovery) goes through exoPlayer.prepare(), which clears the error.
    */
   internal fun resetForNewLoad() {
     resetRetryTimer()
@@ -1215,8 +1228,8 @@ class Player(internal val context: Context) {
     val backwardJumpIntervalChanged =
       previousOptions.backwardJumpInterval != options.backwardJumpInterval
     val capabilitiesChanged = previousOptions.capabilities != options.capabilities
-    val notificationButtonsChanged =
-      previousOptions.notificationButtons != options.notificationButtons
+    val remoteButtonLayoutChanged =
+      !previousOptions.remoteButtonLayout.sameAs(options.remoteButtonLayout)
     val appKilledPlaybackBehaviorChanged =
       previousOptions.appKilledPlaybackBehavior != options.appKilledPlaybackBehavior
 
@@ -1226,7 +1239,7 @@ class Player(internal val context: Context) {
         forwardJumpIntervalChanged ||
         backwardJumpIntervalChanged ||
         capabilitiesChanged ||
-        notificationButtonsChanged ||
+        remoteButtonLayoutChanged ||
         appKilledPlaybackBehaviorChanged
 
     // Apply only changed properties
@@ -1244,13 +1257,22 @@ class Player(internal val context: Context) {
       setProgressUpdateInterval(options.progressUpdateEventInterval)
     }
 
-    if (capabilitiesChanged || notificationButtonsChanged) {
+    // The jump intervals pick the button icons (ICON_SKIP_BACK_15 and friends), so a changed
+    // interval has to rebuild the layout even when capabilities and placement are untouched.
+    if (
+      capabilitiesChanged ||
+        remoteButtonLayoutChanged ||
+        forwardJumpIntervalChanged ||
+        backwardJumpIntervalChanged
+    ) {
       val searchAvailable = browser?.browserManager?.config?.hasSearch ?: false
       mediaSessionCallback.updateMediaSession(
         mediaSession,
         options.capabilities,
-        options.notificationButtons,
+        options.remoteButtonLayout,
         searchAvailable,
+        options.forwardJumpInterval,
+        options.backwardJumpInterval,
       )
     }
 

package/android/src/main/java/com/audiobrowser/player/RetryLoadErrorHandlingPolicy.kt

@@ -107,7 +107,8 @@ class RetryLoadErrorHandlingPolicy(
    */
   private fun exhaustedBudget(currentTime: Long): String? {
     firstErrorTime?.let { start ->
-      if (currentTime - start >= maxRetryDurationMs) return "max retry duration ($maxRetryDurationMs ms)"
+      if (currentTime - start >= maxRetryDurationMs)
+        return "max retry duration ($maxRetryDurationMs ms)"
     }
     if (!hasPlayed() && isOnline()) {
       firstOnlineErrorTime?.let { start ->

package/android/src/main/java/com/audiobrowser/player/TransformingDataSource.kt

@@ -113,7 +113,8 @@ class TransformingDataSource(private val upstream: DataSource, private val facto
    * installs the `IcyDataSource` that emits in-stream ICY/Shoutcast song metadata via
    * `Player.Listener.onMetadata`. The `DataSource` default returns an empty map, so without this
    * override this transparent wrapper would swallow the ICY headers — playback keeps working but
-   * `onMetadata` never fires (live "now playing" song goes missing).
+   * `onMetadata` never fires (live "now playing" song goes missing). Swallowing them also leaves
+   * the interleaved metadata bytes in the audio stream, where they decode as audible chirping.
    */
   override fun getResponseHeaders(): Map<String, List<String>> {
     return upstream.responseHeaders

package/android/src/main/java/com/audiobrowser/tls/AiaCertChaser.kt

@@ -1,6 +1,7 @@
 package com.audiobrowser.tls
 
 import java.security.cert.X509Certificate
+import javax.security.auth.x500.X500Principal
 
 /**
  * Fills in missing intermediate CA certificates by following the Authority Information Access (AIA)
@@ -14,6 +15,18 @@ import java.security.cert.X509Certificate
  * found".
  */
 object AiaCertChaser {
+  /** How many distinct CA-Issuers URLs from one certificate are worth trying. */
+  const val MAX_URLS_PER_CERT = 3
+
+  /**
+   * Wall-clock ceiling on one chain-completion attempt, across all of its fetches. The deadline it
+   * implies is handed to every fetch, whose connects, handshakes, reads and redirects are all
+   * clipped to the time remaining — so the whole walk ends at the deadline. The one thing it cannot
+   * cut short is a DNS lookup already in flight (Java exposes no timeout for resolution), so the
+   * true bound is this budget plus at most one lookup's duration.
+   */
+  const val MAX_CHASE_MILLIS = 20_000L
+
   /** Authority Information Access extension. */
   private const val AIA_OID = "1.3.6.1.5.5.7.1.1"
 
@@ -69,8 +82,9 @@ object AiaCertChaser {
 
   /**
    * Walks up from the presented chain, fetching each missing issuer via its predecessor's AIA "CA
-   * Issuers" pointer, until it reaches a self-signed certificate, an issuer that cannot be fetched,
-   * or [maxIntermediates] additions. Returns the (possibly extended) chain.
+   * Issuers" pointer, until it reaches a certificate issued by one of [anchorSubjects], a
+   * self-signed certificate, an issuer that cannot be fetched, or [maxIntermediates] additions.
+   * Returns the (possibly extended) chain.
    *
    * Only ever *adds* certificates — the caller is still responsible for validating the completed
    * chain against the system trust anchors, so this can never cause an untrusted chain to be
@@ -78,25 +92,52 @@ object AiaCertChaser {
    * selected (defends against an AIA pointer to an unrelated certificate, and picks the right one
    * out of a multi-certificate PKCS#7 bundle).
    *
+   * @param anchorSubjects the subjects of the caller's trust anchors. A chain whose top is already
+   *   issued by one of them is not missing anything, so nothing is fetched — chasing could not help
+   *   and the fetch would be a blocking round trip to a host named by a certificate that just
+   *   failed validation. This is what keeps an expired-but-complete chain, a hostname mismatch or
+   *   any other non-path failure from triggering a chase, and it stops the genuine
+   *   missing-intermediate case one hop early, where the chain reaches a root the caller already
+   *   trusts. Empty means "unknown", and the walk runs to one of the other stopping conditions.
+   * @param maxUrlsPerCert how many of a certificate's distinct CA-Issuers URLs are tried before
+   *   giving up on it. The extension is authored by the same server that failed validation and
+   *   nothing limits how many URLs it may list — a leaf can carry hundreds — while each one costs a
+   *   blocking connect on the handshake thread. Real CAs publish one. Duplicates are collapsed
+   *   before the cap, so the cap buys distinct hosts, not repeat visits to one dead one.
+   * @param budgetMs wall-clock ceiling on the whole walk. It is checked before each fetch, and the
+   *   deadline it implies is passed to [fetch], which is expected to clip its own connects,
+   *   handshakes, reads and redirects to the time remaining — so the budget bounds the fetches
+   *   themselves, not just how many of them start.
    * @param fetch resolves a CA-Issuers URL to its candidate certificates (e.g. every certificate in
-   *   a PKCS#7 bundle); empty if nothing could be retrieved.
+   *   a PKCS#7 bundle), giving up no later than `deadlineNanos` (absolute, [nowNanos] origin);
+   *   empty if nothing could be retrieved.
    */
   fun completeChain(
     presented: List<X509Certificate>,
+    anchorSubjects: Set<X500Principal> = emptySet(),
     maxIntermediates: Int = 5,
-    fetch: (url: String) -> List<X509Certificate>,
+    maxUrlsPerCert: Int = MAX_URLS_PER_CERT,
+    budgetMs: Long = MAX_CHASE_MILLIS,
+    nowNanos: () -> Long = System::nanoTime,
+    fetch: (url: String, deadlineNanos: Long) -> List<X509Certificate>,
   ): List<X509Certificate> {
     if (presented.isEmpty()) return presented
     val chain = presented.toMutableList()
     val seen = HashSet(chain)
+    val deadline = nowNanos() + budgetMs * 1_000_000
     var added = 0
     while (added < maxIntermediates) {
       val last = chain.last()
       if (last.subjectX500Principal == last.issuerX500Principal) break // self-signed root
+      if (last.issuerX500Principal in anchorSubjects) break // already reaches a trust anchor
       val issuer =
         extractCaIssuerUrls(last)
           .asSequence()
-          .flatMap { url -> runCatching { fetch(url) }.getOrElse { emptyList() } }
+          .distinct()
+          .take(maxUrlsPerCert)
+          // Subtraction, not `>`: overflow-safe across nanoTime's arbitrary origin.
+          .takeWhile { nowNanos() - deadline < 0 }
+          .flatMap { url -> runCatching { fetch(url, deadline) }.getOrElse { emptyList() } }
           .firstOrNull { it.subjectX500Principal == last.issuerX500Principal } ?: break
       if (!seen.add(issuer)) break // cycle guard
       chain.add(issuer)
@@ -106,9 +147,13 @@ object AiaCertChaser {
   }
 
   /**
-   * Minimal DER TLV reader over a byte buffer. Does no bounds-checking by design: truncated or
-   * malformed input throws (e.g. [IndexOutOfBoundsException]), which the callers above expect and
-   * turn into "no AIA".
+   * Minimal DER TLV reader over a byte buffer. Malformed input throws [IllegalArgumentException],
+   * which the callers above expect and turn into "no AIA".
+   *
+   * Every read is bounds-checked, and a declared length is rejected unless it is non-negative and
+   * within the buffer. Both matter: the extension bytes come from a server-presented certificate,
+   * so a length that shifts into a negative Int would rewind `pos` and spin [extractCaIssuerUrls]'s
+   * loop forever on the handshake thread rather than failing.
    */
   private class DerReader(private val buf: ByteArray) {
     private var pos = 0
@@ -116,17 +161,28 @@ object AiaCertChaser {
     fun hasNext(): Boolean = pos < buf.size
 
     fun read(): Tlv {
-      val tag = buf[pos++].toInt() and 0xFF
-      var len = buf[pos++].toInt() and 0xFF
+      val tag = readByte()
+      var len = readByte()
       if (len and 0x80 != 0) {
+        // Long form: the low bits give the number of length bytes. Four already covers any
+        // buffer that fits in memory; more would overflow the Int we shift them into. The
+        // indefinite form (0x80, i.e. zero length bytes) is not valid DER.
         val numBytes = len and 0x7F
+        require(numBytes in 1..4) { "unsupported DER length form: $numBytes length bytes" }
         len = 0
-        repeat(numBytes) { len = (len shl 8) or (buf[pos++].toInt() and 0xFF) }
+        repeat(numBytes) { len = (len shl 8) or readByte() }
+        require(len >= 0) { "DER length overflows Int" }
       }
+      require(len <= buf.size - pos) { "DER length $len runs past the end of the buffer" }
       val tlv = Tlv(buf, tag, pos, len)
       pos += len
       return tlv
     }
+
+    private fun readByte(): Int {
+      require(pos < buf.size) { "truncated DER" }
+      return buf[pos++].toInt() and 0xFF
+    }
   }
 
   /** A parsed tag-length-value: the tag and a view of its content bytes. */

package/android/src/main/java/com/audiobrowser/tls/AiaChasingExtendedTrustManager.kt

@@ -0,0 +1,168 @@
+package com.audiobrowser.tls
+
+import android.os.Build
+import androidx.annotation.RequiresApi
+import java.lang.reflect.InvocationTargetException
+import java.lang.reflect.Method
+import java.net.Socket
+import java.security.cert.CertificateException
+import java.security.cert.X509Certificate
+import javax.net.ssl.SSLEngine
+import javax.net.ssl.X509ExtendedTrustManager
+import javax.net.ssl.X509TrustManager
+import javax.security.auth.x500.X500Principal
+
+/**
+ * The [AiaChasingTrustManager] behaviour, as an [X509ExtendedTrustManager].
+ *
+ * The socket- and engine-aware overloads are the ones the platform actually calls, and they are not
+ * optional. Android's default trust manager is a `RootTrustManager`, which extends
+ * [X509ExtendedTrustManager] and whose two-argument `checkServerTrusted` throws unconditionally
+ * once the app declares any `<domain-config>` in its network security config:
+ * > Domain specific configurations require that hostname aware
+ * > checkServerTrusted(X509Certificate[], String, String) is used
+ *
+ * Wrapping it in a plain [X509TrustManager] hides those overloads, so conscrypt falls through to
+ * the two-argument form and *every* HTTPS connection in the process fails. The socket overload is
+ * also where endpoint identification happens for a raw `SSLSocket` configured with
+ * `endpointIdentificationAlgorithm = "HTTPS"`; skipping it skips hostname verification.
+ *
+ * [X509ExtendedTrustManager] is API 24+, hence the split from [AiaChasingTrustManager] — see
+ * [AiaTls.trustManager], which picks by SDK level. Per-domain network security configs are
+ * themselves API 24+, so the plain variant on 23 loses nothing.
+ *
+ * @param delegate the wrapped trust manager, normally the platform default.
+ * @param fetch resolves a CA-Issuers URL to its candidate certificates, giving up no later than
+ *   `deadlineNanos`.
+ */
+@RequiresApi(Build.VERSION_CODES.N)
+class AiaChasingExtendedTrustManager(
+  private val delegate: X509TrustManager,
+  private val fetch: (url: String, deadlineNanos: Long) -> List<X509Certificate>,
+) : X509ExtendedTrustManager() {
+
+  /** The delegate's own extended overloads, when it has them. */
+  private val extended = delegate as? X509ExtendedTrustManager
+
+  private val anchorSubjects: Set<X500Principal> by lazy { delegate.anchorSubjects() }
+
+  /**
+   * The delegate's Android-specific hostname-aware check, if it has one.
+   *
+   * `android.net.http.X509TrustManagerExtensions` — how an HTTP client reaches per-host certificate
+   * pinning — locates this method reflectively and refuses a trust manager that lacks it. It is not
+   * part of [X509ExtendedTrustManager], and `RootTrustManager` is not a public type, so it is
+   * forwarded reflectively rather than overridden.
+   */
+  private val hostAwareCheck: Method? by lazy {
+    runCatching {
+        delegate.javaClass.getMethod(
+          "checkServerTrusted",
+          Array<X509Certificate>::class.java,
+          String::class.java,
+          String::class.java,
+        )
+      }
+      .getOrNull()
+  }
+
+  override fun checkServerTrusted(chain: Array<X509Certificate>, authType: String) =
+    withAiaRetry(chain, anchorSubjects, fetch) { delegate.checkServerTrusted(it, authType) }
+
+  override fun checkServerTrusted(
+    chain: Array<X509Certificate>,
+    authType: String,
+    socket: Socket?,
+  ) =
+    withAiaRetry(chain, anchorSubjects, fetch) {
+      // A delegate without the extended overloads cannot be hostname-aware in the first place,
+      // so falling back to its two-argument form loses nothing it could have offered.
+      extended?.checkServerTrusted(it, authType, socket)
+        ?: delegate.checkServerTrusted(it, authType)
+    }
+
+  override fun checkServerTrusted(
+    chain: Array<X509Certificate>,
+    authType: String,
+    engine: SSLEngine?,
+  ) =
+    withAiaRetry(chain, anchorSubjects, fetch) {
+      extended?.checkServerTrusted(it, authType, engine)
+        ?: delegate.checkServerTrusted(it, authType)
+    }
+
+  /**
+   * The signature `X509TrustManagerExtensions` looks for: validates against [host] and returns the
+   * chain it accepted. Kept in step with the other overloads, AIA retry included, so installing
+   * this wrapper does not cost a consumer its certificate pinning.
+   */
+  @Suppress("unused") // called reflectively
+  fun checkServerTrusted(
+    chain: Array<X509Certificate>,
+    authType: String,
+    host: String,
+  ): List<X509Certificate> {
+    var accepted: List<X509Certificate> = emptyList()
+    val method = hostAwareCheck
+    withAiaRetry(chain, anchorSubjects, fetch) { checked ->
+      // Whichever chain passed is the one to report — reporting the originally presented chain
+      // would hand a pinning consumer a chain missing the intermediate that made it validate.
+      // `ifEmpty` guards a delegate that reports nothing on success; the checked chain is what
+      // it accepted, so that is the answer.
+      accepted =
+        if (method != null)
+          invokeHostAware(method, checked, authType, host).ifEmpty { checked.toList() }
+        else {
+          // Same routing as the other overloads: an extended delegate may refuse its
+          // two-argument form outright (the domain-config case), so prefer its socket overload.
+          extended?.checkServerTrusted(checked, authType, null as Socket?)
+            ?: delegate.checkServerTrusted(checked, authType)
+          checked.toList()
+        }
+    }
+    return accepted
+  }
+
+  @Suppress("UNCHECKED_CAST")
+  private fun invokeHostAware(
+    method: Method,
+    chain: Array<X509Certificate>,
+    authType: String,
+    host: String,
+  ): List<X509Certificate> =
+    try {
+      method.invoke(delegate, chain, authType, host) as List<X509Certificate>
+    } catch (e: InvocationTargetException) {
+      // Unwrap, so a rejection still reaches withAiaRetry as the CertificateException it is.
+      when (val cause = e.targetException) {
+        is CertificateException -> throw cause
+        is RuntimeException -> throw cause
+        else -> throw CertificateException(cause)
+      }
+    }
+
+  // Client certificates are the app's own; there is nothing to chase.
+
+  override fun checkClientTrusted(chain: Array<X509Certificate>, authType: String) =
+    delegate.checkClientTrusted(chain, authType)
+
+  override fun checkClientTrusted(
+    chain: Array<X509Certificate>,
+    authType: String,
+    socket: Socket?,
+  ) {
+    extended?.checkClientTrusted(chain, authType, socket)
+      ?: delegate.checkClientTrusted(chain, authType)
+  }
+
+  override fun checkClientTrusted(
+    chain: Array<X509Certificate>,
+    authType: String,
+    engine: SSLEngine?,
+  ) {
+    extended?.checkClientTrusted(chain, authType, engine)
+      ?: delegate.checkClientTrusted(chain, authType)
+  }
+
+  override fun getAcceptedIssuers(): Array<X509Certificate> = delegate.acceptedIssuers
+}

package/android/src/main/java/com/audiobrowser/tls/AiaChasingTrustManager.kt

@@ -3,6 +3,7 @@ package com.audiobrowser.tls
 import java.security.cert.CertificateException
 import java.security.cert.X509Certificate
 import javax.net.ssl.X509TrustManager
+import javax.security.auth.x500.X500Principal
 
 /**
  * An [X509TrustManager] that retries validation after filling in missing intermediate certificates
@@ -10,28 +11,71 @@ import javax.net.ssl.X509TrustManager
  *
  * Wraps a [delegate] (typically the platform default trust manager). On the happy path the delegate
  * accepts the server-presented chain on the first try and this adds nothing. Only when the delegate
- * rejects the chain does it attempt AIA chasing — and the *completed* chain is still validated by
- * the same delegate against the system trust anchors, so trust can never be weakened: an untrusted
- * root still fails. See [AiaCertChaser].
+ * rejects the chain *and* the top of the chain is not already issued by one of the delegate's
+ * anchors does it attempt AIA chasing. That gate is an issuer-name test, not a diagnosis: it rules
+ * out the common non-path failures (an expired leaf, a hostname mismatch on a complete chain), but
+ * a chain topping at a root the device does not carry is still chased whatever its real problem
+ * was. Either way the *completed* chain is still validated by the same delegate against the system
+ * trust anchors, so trust can never be weakened: an untrusted root still fails. See
+ * [AiaCertChaser].
+ *
+ * This is the API 23 variant. On 24+ [AiaChasingExtendedTrustManager] is used instead, and must be:
+ * see its documentation for why a plain [X509TrustManager] is not a safe wrapper there.
  */
 class AiaChasingTrustManager(
   private val delegate: X509TrustManager,
-  private val fetch: (url: String) -> List<X509Certificate>,
+  private val fetch: (url: String, deadlineNanos: Long) -> List<X509Certificate>,
 ) : X509TrustManager {
 
-  override fun checkServerTrusted(chain: Array<X509Certificate>, authType: String) {
-    try {
-      delegate.checkServerTrusted(chain, authType)
-    } catch (original: CertificateException) {
-      val completed = AiaCertChaser.completeChain(chain.toList(), fetch = fetch)
-      // Nothing could be added — the original failure stands (don't re-check an unchanged chain).
-      if (completed.size == chain.size) throw original
-      delegate.checkServerTrusted(completed.toTypedArray(), authType)
-    }
-  }
+  private val anchorSubjects: Set<X500Principal> by lazy { delegate.anchorSubjects() }
+
+  override fun checkServerTrusted(chain: Array<X509Certificate>, authType: String) =
+    withAiaRetry(chain, anchorSubjects, fetch) { delegate.checkServerTrusted(it, authType) }
 
   override fun checkClientTrusted(chain: Array<X509Certificate>, authType: String) =
     delegate.checkClientTrusted(chain, authType)
 
   override fun getAcceptedIssuers(): Array<X509Certificate> = delegate.acceptedIssuers
 }
+
+/** The subjects of a trust manager's accepted issuers; empty if it will not say. */
+internal fun X509TrustManager.anchorSubjects(): Set<X500Principal> =
+  runCatching { acceptedIssuers.mapTo(HashSet()) { it.subjectX500Principal } }
+    .getOrElse { emptySet() }
+
+/**
+ * Runs [check], and on rejection retries it once against the AIA-completed chain.
+ *
+ * Nothing is fetched when the presented chain already reaches one of the caller's anchors — see
+ * [AiaCertChaser.completeChain]'s `anchorSubjects`. Without that test *every* failed handshake in
+ * the process, whatever the cause, would make a blocking outbound request to a host named by the
+ * certificate that just failed: an expired certificate, a hostname mismatch and a
+ * certificate-transparency refusal all arrive here as a [CertificateException] from a delegate that
+ * is perfectly happy with the path. (The test is on issuer names, so a chain topping at an unknown
+ * root is still chased even when its real failure was something else.)
+ *
+ * The completed chain goes through the same [check], so trust is never weakened: whatever the
+ * delegate would have refused, it still refuses.
+ */
+internal inline fun withAiaRetry(
+  chain: Array<X509Certificate>,
+  anchorSubjects: Set<X500Principal>,
+  noinline fetch: (url: String, deadlineNanos: Long) -> List<X509Certificate>,
+  check: (Array<X509Certificate>) -> Unit,
+) {
+  try {
+    check(chain)
+  } catch (original: CertificateException) {
+    val completed = AiaCertChaser.completeChain(chain.toList(), anchorSubjects, fetch = fetch)
+    // Nothing could be added — the original failure stands (don't re-check an unchanged chain).
+    if (completed.size == chain.size) throw original
+    try {
+      check(completed.toTypedArray())
+    } catch (retried: CertificateException) {
+      // The chase can change which failure the caller sees (a missing intermediate can turn out
+      // to hide an expiry). Keep the first one attached rather than losing it.
+      retried.addSuppressed(original)
+      throw retried
+    }
+  }
+}

package/android/src/main/java/com/audiobrowser/tls/AiaTls.kt

@@ -1,9 +1,11 @@
 package com.audiobrowser.tls
 
+import android.os.Build
 import java.security.KeyStore
 import javax.net.ssl.SSLContext
 import javax.net.ssl.SSLSocketFactory
 import javax.net.ssl.TrustManagerFactory
+import javax.net.ssl.X509ExtendedTrustManager
 import javax.net.ssl.X509TrustManager
 
 /**
@@ -11,11 +13,24 @@ import javax.net.ssl.X509TrustManager
  * following the leaf's Authority Information Access (AIA) "CA Issuers" pointer — the behaviour
  * Apple's Secure Transport has by default but Android's lacks.
  *
- * The returned components are side-effect-free: they wrap the platform default trust manager and
- * only ever *add* a missing intermediate before re-validating against the same system trust
- * anchors, so they cannot weaken trust. Installing them as a process default (e.g.
- * `HttpsURLConnection.setDefaultSSLSocketFactory(AiaTls.socketFactory())`) is the caller's
- * decision.
+ * The returned components wrap the platform default trust manager and only ever *add* a missing
+ * intermediate before re-validating against the same system trust anchors, so they cannot weaken
+ * trust: whatever the platform would have refused, it still refuses.
+ *
+ * What they are not is side-effect-free. Completing a chain means fetching the missing intermediate
+ * from a URL named by the certificate that just failed to validate — so a rejected handshake can
+ * make an outbound request to a host, port and path of that server's choosing, over cleartext, not
+ * subject to the app's `NetworkSecurityPolicy`. That is inherent to AIA chasing and is what
+ * browsers and Apple's Secure Transport do too, but it is a real consequence of installing this,
+ * and it is bounded rather than absent: see [CachingCertificateFetcher] for the per-fetch limits
+ * and [AiaCertChaser.MAX_CHASE_MILLIS] for the wall-clock ceiling on the whole chase. The fetch is
+ * skipped when the chain already reaches one of the system anchors — an issuer-name test, so it
+ * spares the common expired-leaf and hostname-mismatch failures, but a chain topping at a root the
+ * device does not carry is still chased whatever its real problem was.
+ *
+ * Installing them as a process default (e.g.
+ * `HttpsURLConnection.setDefaultSSLSocketFactory(AiaTls.socketFactory())`) applies that to every
+ * connection in the process, and is the caller's decision.
  */
 object AiaTls {
 
@@ -27,10 +42,23 @@ object AiaTls {
   fun socketFactory(): SSLSocketFactory =
     SSLContext.getInstance("TLS").apply { init(null, arrayOf(trustManager()), null) }.socketFactory
 
-  /** An [X509TrustManager] wrapping the platform default with AIA intermediate chasing. */
+  /**
+   * An [X509TrustManager] wrapping the platform default with AIA intermediate chasing.
+   *
+   * On API 24+ this is an [X509ExtendedTrustManager]. That is not cosmetic: the platform's default
+   * trust manager rejects the two-argument `checkServerTrusted` outright once the app declares any
+   * `<domain-config>`, so a plain wrapper would break every HTTPS connection in the process. See
+   * [AiaChasingExtendedTrustManager].
+   */
   fun trustManager(): X509TrustManager {
     val fetcher = CachingCertificateFetcher()
-    return AiaChasingTrustManager(systemTrustManager()) { fetcher.fetch(it) }
+    val fetch = { url: String, deadlineNanos: Long -> fetcher.fetch(url, deadlineNanos) }
+    val system = systemTrustManager()
+    return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
+      AiaChasingExtendedTrustManager(system, fetch)
+    } else {
+      AiaChasingTrustManager(system, fetch)
+    }
   }
 
   private fun systemTrustManager(): X509TrustManager {