react-native-audio-browser 0.2.0-next.10 → 0.2.0-next.12

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

@@ -20,6 +20,7 @@ import com.audiobrowser.browser.displayArtworkSource
 import com.audiobrowser.browser.resolveArtworkUrl
 import com.audiobrowser.browser.unattributedArtworkSource
 import com.audiobrowser.extension.NumberExt.Companion.toSeconds
+import com.audiobrowser.extension.identity
 import com.audiobrowser.model.PlayerSetupOptions
 import com.audiobrowser.model.PlayerUpdateOptions
 import com.audiobrowser.util.CoilBitmapLoader
@@ -36,7 +37,6 @@ import com.margelo.nitro.audiobrowser.ImageSource
 import com.margelo.nitro.audiobrowser.NativeGateRequest
 import com.margelo.nitro.audiobrowser.NowPlayingMetadata
 import com.margelo.nitro.audiobrowser.Playback
-import com.margelo.nitro.audiobrowser.PlaybackActiveTrackChangedEvent
 import com.margelo.nitro.audiobrowser.PlaybackError
 import com.margelo.nitro.audiobrowser.PlaybackPlayWhenReadyChangedEvent
 import com.margelo.nitro.audiobrowser.PlaybackProgressUpdatedEvent
@@ -351,7 +351,7 @@ class Player(internal val context: Context) {
     get() = exoPlayer.nextMediaItemIndex == C.INDEX_UNSET
 
   /**
-   * The source path from which the current queue was expanded (e.g., from a contextual URL). Used
+   * The source path from which the current queue was expanded (e.g., from a contextual path). Used
    * to avoid re-expanding the queue when selecting tracks from the same source.
    */
   var queueSourcePath: String? = null
@@ -657,7 +657,7 @@ class Player(internal val context: Context) {
    * @param tracks The tracks to set as the new queue.
    * @param startIndex The index to start playback from (default: 0).
    * @param startPositionMs The position in milliseconds to start from (default: 0).
-   * @param sourcePath Optional path from which this queue was expanded (for contextual URL
+   * @param sourcePath Optional path from which this queue was expanded (for contextual path
    *   optimization).
    */
   fun setQueue(
@@ -685,17 +685,27 @@ class Player(internal val context: Context) {
   /**
    * Sets the favorited state of the currently playing track. Updates the heart icon in media
    * controllers without interrupting playback.
+   *
+   * @return whether the gesture applied — false only when there is no current track (nothing to
+   *   favorite), so MediaSession callers can report an invalid state instead of a success the
+   *   controller then watches revert.
    */
-  fun setActiveTrackFavorited(favorited: Boolean) {
-    val currentTrack = this.currentTrack ?: return
+  fun setActiveTrackFavorited(favorited: Boolean): Boolean {
+    val currentTrack = this.currentTrack ?: return false
 
     // Persist to the native favorites cache regardless of player state — the
     // user's gesture is durable even when there's no active media item to
-    // update (queue tear-down, between-track gaps, etc.).
-    currentTrack.src?.let { src -> browser?.browserManager?.updateFavorite(src, favorited) }
+    // update (queue tear-down, between-track gaps, etc.). Keyed by the track
+    // identity (id when non-blank, else src).
+    currentTrack.identity?.let { identity ->
+      browser?.browserManager?.updateFavorite(identity, favorited)
+    }
 
+    // Cache written above: the gesture is durably recorded even without a media
+    // item to restamp (queue tear-down, between-track gaps) — that counts as
+    // applied; there is also no visible heart to revert in that state.
     val index = exoPlayer.currentMediaItemIndex
-    if (index == C.INDEX_UNSET) return
+    if (index == C.INDEX_UNSET) return true
 
     // Create updated Track with new favorited state
     val updatedTrack = currentTrack.copy(favorited = favorited)
@@ -719,28 +729,23 @@ class Player(internal val context: Context) {
     // Update the heart button icon in notification/Android Auto
     updateFavoriteButtonState(favorited)
 
-    // Notify JS of the favorite state change
+    // Notify JS of the favorite state change. This is the ONLY emit: a favorite
+    // toggle is an in-place mutation of the active track, not a transition —
+    // onPlaybackActiveTrackChanged / onPlaybackQueueChanged stay
+    // transition-only, and the useActiveTrack / useQueue hooks subscribe to
+    // onFavoriteChanged themselves.
     callbacks?.onFavoriteChanged(FavoriteChangedEvent(updatedTrack, favorited))
-
-    // Emit active track changed so useActiveTrack() hook updates
-    val activeTrackEvent =
-      PlaybackActiveTrackChangedEvent(
-        lastIndex = index.toDouble(),
-        lastTrack = currentTrack,
-        lastPosition = exoPlayer.currentPosition.toSeconds(),
-        index = index.toDouble(),
-        track = updatedTrack,
-      )
-    callbacks?.onPlaybackActiveTrackChanged(activeTrackEvent)
-
-    // Emit queue changed so useQueue() hook updates
-    callbacks?.onPlaybackQueueChanged(tracks)
+    return true
   }
 
-  /** Toggles the favorited state of the currently playing track. */
-  fun toggleActiveTrackFavorited() {
-    val currentTrack = this.currentTrack ?: return
-    setActiveTrackFavorited(currentTrack.favorited != true)
+  /**
+   * Toggles the favorited state of the currently playing track.
+   *
+   * @return whether the toggle applied — false when there is no current track.
+   */
+  fun toggleActiveTrackFavorited(): Boolean {
+    val currentTrack = this.currentTrack ?: return false
+    return setActiveTrackFavorited(currentTrack.favorited != true)
   }
 
   // MARK: - Now Playing Metadata
@@ -926,10 +931,23 @@ class Player(internal val context: Context) {
     }
   }
 
-  /** Jump to the live edge (default position) of a live item; no-op otherwise. */
+  /**
+   * Jump to the live edge of the current track; no-op unless it declares `live` — the track's own
+   * declaration is the gate (matching iOS and the spec), not ExoPlayer's stream-derived liveness,
+   * which never marks progressive ICY radio live. A stream with a live window seeks to its edge;
+   * anything else reconnects — for a non-seekable stream a fresh connection IS the live edge. A
+   * stale URL recovers through the failure-armed re-resolve in [TransformingDataSource].
+   */
   fun seekToLiveEdge() {
+    if (currentTrack?.live != true) return
     if (exoPlayer.isCurrentMediaItemLive) {
       exoPlayer.seekToDefaultPosition()
+    } else {
+      // ExoPlayer.prepare() only re-prepares from STATE_IDLE, hence the raw stop() — not
+      // Player.stop(), which would drop the play intent this reconnect must preserve.
+      exoPlayer.stop()
+      exoPlayer.seekToDefaultPosition()
+      exoPlayer.prepare()
     }
   }
 
@@ -1249,8 +1267,8 @@ class Player(internal val context: Context) {
 
     if (capabilitiesChanged) {
       // The `favorite` capability is the single favoriting switch — propagate
-      // its match mode to the browser so it can hydrate row hearts.
-      browser?.browserManager?.setFavoriteMatch(options.capabilities.favoriteMatch)
+      // it to the browser so it can hydrate row hearts.
+      browser?.browserManager?.setFavoriteEnabled(options.capabilities.favoriteEnabled)
     }
 
     if (progressUpdateEventIntervalChanged) {

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

@@ -1,20 +1,7 @@
 package com.audiobrowser.player
 
-import com.margelo.nitro.audiobrowser.FavoritesMatchMode
 import com.margelo.nitro.audiobrowser.PlayerCapabilities
 
-/**
- * Resolved favorite match mode, or null when favoriting is disabled.
- *
- * `false`/unset → null; `true` → EXACT; `{ match }` → that match.
- */
-val PlayerCapabilities.favoriteMatch: FavoritesMatchMode?
-  get() =
-    favorite?.match(
-      first = { enabled -> if (enabled) FavoritesMatchMode.EXACT else null },
-      second = { config -> config.match },
-    )
-
-/** Whether the favorite/like control is enabled. */
+/** Whether the favorite/like control is enabled. Opt-in: only an explicit `true` enables it. */
 val PlayerCapabilities.favoriteEnabled: Boolean
-  get() = favoriteMatch != null
+  get() = favorite == true

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)

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

@@ -1,11 +1,16 @@
 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].
@@ -18,9 +23,8 @@ import javax.net.ssl.X509TrustManager
  * > 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 — and, because the
- * wrapper treats a [CertificateException] as its cue to chase AIA, fails slowly. The socket
- * overload is also where endpoint identification happens for a raw `SSLSocket` configured with
+ * 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
@@ -28,25 +32,49 @@ import javax.net.ssl.X509TrustManager
  * 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.
+ * @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) -> List<X509Certificate>,
+  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) { delegate.checkServerTrusted(it, authType) }
+    withAiaRetry(chain, anchorSubjects, fetch) { delegate.checkServerTrusted(it, authType) }
 
   override fun checkServerTrusted(
     chain: Array<X509Certificate>,
     authType: String,
     socket: Socket?,
   ) =
-    withAiaRetry(chain) {
+    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)
@@ -58,11 +86,61 @@ class AiaChasingExtendedTrustManager(
     authType: String,
     engine: SSLEngine?,
   ) =
-    withAiaRetry(chain) {
+    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) =
@@ -87,23 +165,4 @@ class AiaChasingExtendedTrustManager(
   }
 
   override fun getAcceptedIssuers(): Array<X509Certificate> = delegate.acceptedIssuers
-
-  /**
-   * Runs [check], and on rejection retries it once against the AIA-completed chain. The completed
-   * chain goes through the same [check], so trust is never weakened: whatever the delegate would
-   * have refused, it still refuses.
-   */
-  private inline fun withAiaRetry(
-    chain: Array<X509Certificate>,
-    check: (Array<X509Certificate>) -> Unit,
-  ) {
-    try {
-      check(chain)
-    } 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
-      check(completed.toTypedArray())
-    }
-  }
 }

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

@@ -5,6 +5,7 @@ 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
 
 /**
@@ -12,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 {
 
@@ -38,7 +52,7 @@ object AiaTls {
    */
   fun trustManager(): X509TrustManager {
     val fetcher = CachingCertificateFetcher()
-    val fetch = { url: String -> fetcher.fetch(url) }
+    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)