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

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

@@ -8,39 +8,69 @@ import java.net.Socket
 import java.net.URL
 import java.security.cert.CertificateFactory
 import java.security.cert.X509Certificate
-import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicBoolean
 import javax.net.ssl.HttpsURLConnection
 import javax.net.ssl.SSLContext
+import javax.net.ssl.SSLSocket
 import javax.net.ssl.SSLSocketFactory
+import kotlin.concurrent.thread
 import timber.log.Timber
 
 /**
  * Fetches and caches issuer certificates from AIA "CA Issuers" URLs. Used by
  * [AiaChasingTrustManager] to fill in intermediates a server failed to send.
  *
- * Runs on the TLS handshake thread, so it uses short timeouts and never throws — a failed or slow
- * fetch resolves to an empty list (the handshake then fails exactly as it would have without AIA
- * chasing). Only non-empty results are cached, so the (typically `http`) round-trip happens at most
- * once per intermediate for the process lifetime while transient failures stay retryable.
+ * Runs on the TLS handshake thread, so it is bounded on every axis and never throws — a failed,
+ * oversized or slow fetch resolves to an empty list, and the handshake then fails exactly as it
+ * would have without AIA chasing. Every input here is chosen by a server we are already failing to
+ * validate: the AIA extension names the host, port and path, and then that host chooses the
+ * response. So:
+ * - the URL is rejected unless it is free of control characters ([isSafeUrl]),
+ * - a response is capped at [MAX_RESPONSE_BYTES] and [MAX_RESPONSE_MILLIS],
+ * - at most [MAX_REDIRECTS] redirects are followed,
+ * - the cache holds at most [MAX_CACHE_ENTRIES], and only successful fetches, so a round trip
+ *   happens at most once per intermediate while transient failures stay retryable,
+ * - the whole call — every connect, handshake, read and redirect hop — ends at the caller's
+ *   `deadlineNanos`: each per-operation timeout is clipped to the time remaining, connect and read
+ *   by their socket timeouts and the TLS handshake plus the exchange by a watchdog that closes the
+ *   underlying transport, and once the deadline has passed nothing further is even started.
  *
- * Responses are capped at [MAX_RESPONSE_BYTES]. The URL comes from a server-presented certificate,
- * so the host, port and path are chosen by whoever we are failing to validate; the read timeout is
- * per-read and would not stop a slow drip of unbounded length. A certificate is a few kilobytes and
- * even a PKCS#7 bundle a few dozen, so the cap is far above anything legitimate.
+ * The one step no deadline reaches is DNS: `InetSocketAddress` resolves synchronously and Java
+ * exposes no timeout for it, so a lookup begun just inside the deadline can overrun it by its own
+ * duration. A lookup is never *started* past the deadline, and [AiaCertChaser.MAX_URLS_PER_CERT]
+ * keeps the count down — a certificate can only make us resolve a few names, not a few hundred.
  *
- * `http` fetches go over a raw [Socket] rather than `HttpURLConnection`. CA "CA Issuers" URLs are
- * virtually always plain `http` (the CA/Browser Forum Baseline Requirements mandate it, to avoid a
- * chicken-and-egg TLS dependency when fetching the cert needed to complete a TLS chain), but
- * Android blocks cleartext `HttpURLConnection` traffic by default on apps targeting API 28+. A raw
- * socket is not subject to `NetworkSecurityPolicy`, so the fetch succeeds regardless of the host
- * app's cleartext setting — safely, because the fetched certificate is still cryptographically
- * verified to be the real issuer before [AiaChasingTrustManager] trusts it.
+ * Both schemes go over a raw [Socket] rather than `HttpURLConnection`. For `http` that is because
+ * CA "CA Issuers" URLs are virtually always plain `http` — the CA/Browser Forum Baseline
+ * Requirements mandate it, to avoid a chicken-and-egg TLS dependency when fetching the certificate
+ * needed to complete a TLS chain — while Android blocks cleartext `HttpURLConnection` traffic by
+ * default on apps targeting API 28+. A raw socket is not subject to `NetworkSecurityPolicy`, so the
+ * fetch succeeds regardless of the host app's cleartext setting; safely, because the fetched
+ * certificate is still cryptographically verified to be the real issuer before
+ * [AiaChasingTrustManager] trusts it.
+ *
+ * For `https` it is because `HttpURLConnection.getInputStream()` performs the connect, request and
+ * response *headers* before returning a stream, so a read cap applied to that stream bounds only
+ * the body: a server dripping header bytes just inside the per-read timeout would hold the
+ * handshake thread for as long as it liked. Reading the headers ourselves puts them inside the same
+ * budget as the body. It also keeps one redirect policy — the platform stack would otherwise follow
+ * its own, ignoring [MAX_REDIRECTS].
  */
 class CachingCertificateFetcher(
   private val connectTimeoutMs: Int = 5_000,
   private val readTimeoutMs: Int = 5_000,
+  private val nowNanos: () -> Long = System::nanoTime,
 ) {
-  private val cache = ConcurrentHashMap<String, List<X509Certificate>>()
+  /**
+   * Bounded, least-recently-used. An attacker can name any URL and serve any parseable certificate
+   * from it, so an unbounded map would retain a megabyte per hostile handshake for the process
+   * lifetime. A real app needs a handful of intermediates.
+   */
+  private val cache =
+    object : LinkedHashMap<String, List<X509Certificate>>(16, 0.75f, true) {
+      override fun removeEldestEntry(eldest: Map.Entry<String, List<X509Certificate>>) =
+        size > MAX_CACHE_ENTRIES
+    }
 
   /**
    * A plain system-default socket factory for `https` AIA fetches. Without it the fetch would use
@@ -51,98 +81,243 @@ class CachingCertificateFetcher(
     SSLContext.getInstance("TLS").apply { init(null, null, null) }.socketFactory
   }
 
-  fun fetch(url: String): List<X509Certificate> {
-    cache[url]?.let {
-      return it
-    }
-    val certs = download(url)?.let { parseCertificates(it) }.orEmpty()
-    if (certs.isNotEmpty()) cache[url] = certs
+  /**
+   * Fetches the certificates served at [url], giving up no later than [deadlineNanos] — absolute,
+   * on [nowNanos]'s origin. [AiaCertChaser.completeChain] passes its whole-walk deadline here, so
+   * one budget bounds the sum of every fetch it makes. The default covers a standalone call.
+   *
+   * A cache hit is answered even past the deadline — it costs no I/O.
+   */
+  fun fetch(
+    url: String,
+    deadlineNanos: Long = nowNanos() + AiaCertChaser.MAX_CHASE_MILLIS * 1_000_000,
+  ): List<X509Certificate> {
+    synchronized(cache) { cache[url] }
+      ?.let {
+        return it
+      }
+    val certs = download(url, deadlineNanos)?.let { parseCertificates(it) }.orEmpty()
+    if (certs.isNotEmpty()) synchronized(cache) { cache[url] = certs }
     return certs
   }
 
-  private fun download(url: String, redirectsLeft: Int = MAX_REDIRECTS): ByteArray? =
+  /** Milliseconds until [deadlineNanos]; zero or negative once it has passed. */
+  private fun remainingMs(deadlineNanos: Long): Long = (deadlineNanos - nowNanos()) / 1_000_000
+
+  private fun download(
+    url: String,
+    deadlineNanos: Long,
+    redirectsLeft: Int = MAX_REDIRECTS,
+  ): ByteArray? =
     try {
+      // Checked before anything is started — DNS included, since it is the one step below that
+      // no timeout reaches. Redirects recurse through here, so every hop re-checks.
+      require(remainingMs(deadlineNanos) > 0) { "AIA chase budget exhausted" }
       require(isSafeUrl(url)) { "AIA URL contains characters that are not valid in a URL" }
       val parsed = URL(url)
       when (parsed.protocol) {
-        "http" -> downloadCleartext(parsed, redirectsLeft)
-        "https" -> downloadHttps(parsed)
-        else -> null // restrict to http/https — file:, ftp: etc. are never valid CA-issuer sources
+        // restrict to http/https — file:, ftp: etc. are never valid CA-issuer sources
+        "http" -> fetchOverSocket(parsed, deadlineNanos, redirectsLeft, secure = false)
+        "https" -> fetchOverSocket(parsed, deadlineNanos, redirectsLeft, secure = true)
+        else -> null
       }
     } catch (e: Exception) {
-      Timber.w(e, "AIA CA-issuer fetch failed: %s", url)
+      // The URL is attacker-supplied text and this is the one place it survives the safety
+      // check, so it is escaped rather than handed to the log verbatim.
+      Timber.w(e, "AIA CA-issuer fetch failed: %s", sanitizeForLog(url))
       null
     }
 
   /**
-   * `https` AIA fetch over the platform HTTP stack. `https` is never subject to Android's cleartext
-   * policy, so `HttpsURLConnection` is fine here; the plain socket factory keeps the fetch's own
-   * handshake from recursing into AIA chasing.
+   * A connected socket to speak HTTP over, plus the plain TCP transport underneath it. They differ
+   * for `https`: closing an `SSLSocket` writes a `close_notify` alert, which can itself block
+   * against a peer that stopped reading — so anything that needs to *unblock* a stalled call must
+   * close [transport], whose close is immediate and fails every read layered above it.
    */
-  private fun downloadHttps(url: URL): ByteArray? {
-    val connection = url.openConnection() as? HttpsURLConnection ?: return null
-    connection.connectTimeout = connectTimeoutMs
-    connection.readTimeout = readTimeoutMs
-    connection.sslSocketFactory = plainSslSocketFactory
-    return connection.inputStream.use { readCapped(it) }
-  }
+  private class Connection(val socket: Socket, val transport: Socket)
 
-  /**
-   * `http` AIA fetch over a raw socket — see the class doc for why this bypasses
-   * `HttpURLConnection`.
-   */
-  private fun downloadCleartext(url: URL, redirectsLeft: Int): ByteArray? {
+  /** One HTTP/1.0 exchange over a socket, TLS-wrapped when [secure], then redirects. */
+  private fun fetchOverSocket(
+    url: URL,
+    deadlineNanos: Long,
+    redirectsLeft: Int,
+    secure: Boolean,
+  ): ByteArray? {
     val host = url.host
-    val port = if (url.port != -1) url.port else 80
+    val port = if (url.port != -1) url.port else if (secure) 443 else 80
     val path = url.file.ifEmpty { "/" } // URL.file is path + query
+    val connection = connect(host, port, secure, deadlineNanos)
     val raw =
-      Socket().use { socket ->
-        socket.connect(InetSocketAddress(host, port), connectTimeoutMs)
-        socket.soTimeout = readTimeoutMs
-        // HTTP/1.0 + `Connection: close` so the server closes after the body and we can read to EOF
-        // without parsing Content-Length.
-        val request =
-          "GET $path HTTP/1.0\r\n" +
-            "Host: $host\r\n" +
-            "Connection: close\r\n" +
-            "User-Agent: react-native-audio-browser\r\n" +
-            "Accept: */*\r\n\r\n"
-        socket.getOutputStream().apply {
-          write(request.toByteArray(Charsets.ISO_8859_1))
-          flush()
+      try {
+        withWatchdog(
+          minOf(remainingMs(deadlineNanos), connectTimeoutMs + MAX_RESPONSE_MILLIS),
+          abort = { connection.transport.close() },
+        ) {
+          val socket = connection.socket
+          socket.soTimeout = timeoutMs(deadlineNanos, readTimeoutMs)
+          // HTTP/1.0 + `Connection: close` so the server closes after the body and we can read
+          // to EOF without parsing Content-Length. A non-default port belongs in Host, or a
+          // name-based virtual host answers for the wrong site.
+          val hostHeader = if (port == (if (secure) 443 else 80)) host else "$host:$port"
+          val request =
+            "GET $path HTTP/1.0\r\n" +
+              "Host: $hostHeader\r\n" +
+              "Connection: close\r\n" +
+              "User-Agent: react-native-audio-browser\r\n" +
+              "Accept: */*\r\n\r\n"
+          socket.getOutputStream().apply {
+            write(request.toByteArray(Charsets.ISO_8859_1))
+            flush()
+          }
+          socket.getInputStream().use {
+            readCapped(
+              it,
+              budgetMs = minOf(remainingMs(deadlineNanos), MAX_RESPONSE_MILLIS),
+              nowNanos = nowNanos,
+            )
+          }
         }
-        socket.getInputStream().use { readCapped(it) }
+      } finally {
+        // Transport first: its close never blocks and unblocks anything above it, so the
+        // SSLSocket's close_notify attempt afterwards fails fast instead of stalling.
+        runCatching { connection.transport.close() }
+        runCatching { connection.socket.close() }
       } ?: return null
     val response = parseHttpResponse(raw) ?: return null
     return when {
       response.status in 200..299 -> response.body
       response.status in 300..399 && response.location != null && redirectsLeft > 0 ->
-        // Follow CA-issuer redirects (rare). A redirect to `https` falls through to the https path.
-        download(URL(url, response.location).toString(), redirectsLeft - 1)
+        // Follow CA-issuer redirects (rare). `download` is the recursion point, so the target
+        // goes through the same URL check and the same deadline.
+        download(URL(url, response.location).toString(), deadlineNanos, redirectsLeft - 1)
       else -> null
     }
   }
 
+  /**
+   * Connects to [host]:[port], wrapping in TLS when [secure]. Both the connect and the TLS
+   * handshake are clipped to the caller's deadline.
+   *
+   * The TLS socket verifies the hostname explicitly. A raw `SSLSocket` does not do it on its own,
+   * and `SSLParameters.setEndpointIdentificationAlgorithm` is API 24+, so the platform's default
+   * verifier is applied against the negotiated session instead — which works on every supported
+   * level and is the same check `HttpsURLConnection` would have made.
+   */
+  private fun connect(host: String, port: Int, secure: Boolean, deadlineNanos: Long): Connection {
+    val plain = Socket()
+    // Everything from here on closes `plain` if it throws. Android's Socket.connect, unlike
+    // modern OpenJDK's, does not close itself on failure once the descriptor is allocated, so
+    // every unreachable AIA host would otherwise leak one until finalization.
+    var wrapper: SSLSocket? = null
+    return try {
+      plain.connect(InetSocketAddress(host, port), timeoutMs(deadlineNanos, connectTimeoutMs))
+      if (!secure) return Connection(plain, plain)
+      // The handshake is bounded by a watchdog, not by soTimeout: soTimeout is per-read, so a
+      // server drip-feeding handshake bytes would stretch it indefinitely. The watchdog closes
+      // `plain`, the transport — closing the SSLSocket instead would write a close_notify that
+      // can block against the very peer that caused the stall.
+      withWatchdog(
+        minOf(remainingMs(deadlineNanos), connectTimeoutMs + MAX_RESPONSE_MILLIS),
+        abort = { plain.close() },
+      ) {
+        val ssl = plainSslSocketFactory.createSocket(plain, host, port, true) as SSLSocket
+        wrapper = ssl
+        ssl.soTimeout = timeoutMs(deadlineNanos, readTimeoutMs)
+        ssl.startHandshake()
+        require(HttpsURLConnection.getDefaultHostnameVerifier().verify(host, ssl.session)) {
+          "AIA host $host does not match its certificate"
+        }
+        Connection(ssl, plain)
+      }
+    } catch (e: Exception) {
+      runCatching { plain.close() }
+      // The orphaned TLS wrapper too — with the transport already gone its close_notify attempt
+      // fails fast, and this releases the wrapper's own buffers rather than waiting on the GC.
+      runCatching { wrapper?.close() }
+      throw e
+    }
+  }
+
+  /**
+   * A per-operation socket timeout: [perOperationMs] clipped to the deadline, and never 0 ("no
+   * timeout" to a socket) — an already-expired deadline still gets a 1 ms timeout and fails at
+   * once.
+   */
+  private fun timeoutMs(deadlineNanos: Long, perOperationMs: Int): Int =
+    minOf(remainingMs(deadlineNanos), perOperationMs.toLong())
+      .coerceIn(1, Int.MAX_VALUE.toLong())
+      .toInt()
+
+  /**
+   * Runs [body] with a watchdog thread that invokes [abort] once [budgetMs] elapses — unless the
+   * body has already finished, which the done flag makes visible to a watchdog waking at just that
+   * moment, so a successful exchange cannot have its socket closed out from under it.
+   *
+   * The socket timeouts are per-operation and so cannot bound a peer that keeps every individual
+   * read just inside them; [abort] — closing the underlying transport — is what actually ends a
+   * stalled handshake or exchange: the blocked call throws, and a failed fetch is already handled
+   * as "no AIA".
+   */
+  private inline fun <T> withWatchdog(
+    budgetMs: Long,
+    crossinline abort: () -> Unit,
+    body: () -> T,
+  ): T {
+    val done = AtomicBoolean(false)
+    val watchdog =
+      thread(isDaemon = true, name = "aia-fetch-watchdog") {
+        runCatching { Thread.sleep(budgetMs.coerceAtLeast(0)) }
+          .onSuccess { if (!done.get()) runCatching { abort() } }
+      }
+    try {
+      return body()
+    } finally {
+      done.set(true)
+      watchdog.interrupt()
+    }
+  }
+
   companion object {
     private const val MAX_REDIRECTS = 5
 
+    /** Ceiling on how many fetched issuer certificates are retained. */
+    const val MAX_CACHE_ENTRIES = 32
+
+    /** Ceiling on a single AIA response, headers included. */
+    const val MAX_RESPONSE_BYTES = 1 shl 20 // 1 MiB
+
+    /** Ceiling on the wall-clock time spent reading one AIA response. */
+    const val MAX_RESPONSE_MILLIS = 10_000L
+
     /**
      * Whether [url] is free of characters that have no business in a URL.
      *
-     * The cleartext fetch writes the path into a request line on a raw socket, and the URL is an
-     * IA5String copied verbatim out of a certificate a hostile server presented. `java.net.URL`
-     * preserves control characters — `URL("http://host:6379/\r\nSET foo bar")` parses to that host
-     * and port with the CRLF intact in `file` — so without this check a certificate could inject
-     * request lines of its own, to any host and port the device can reach. Space is excluded too:
-     * it would split the request line's target from its HTTP version.
+     * The fetch writes the path into a request line on a raw socket, and the URL is an IA5String
+     * copied verbatim out of a certificate a hostile server presented. `java.net.URL` preserves
+     * control characters — `URL("http://host:6379/\r\nSET foo bar")` parses to that host and port
+     * with the CRLF intact in `file` — so without this check a certificate could inject request
+     * lines of its own, to any host and port the device can reach. Space is excluded too: it would
+     * split the request line's target from its HTTP version.
      */
     fun isSafeUrl(url: String): Boolean = url.none { it.code <= 0x20 || it.code == 0x7F }
 
-    /** Ceiling on a single AIA response body. */
-    const val MAX_RESPONSE_BYTES = 1 shl 20 // 1 MiB
+    /** [text] with anything non-printable replaced, so a log line cannot be forged. */
+    fun sanitizeForLog(text: String): String =
+      text.map { if (it.code <= 0x20 || it.code == 0x7F) '?' else it }.joinToString("")
 
-    /** Ceiling on the wall-clock time spent reading one AIA response. */
-    const val MAX_RESPONSE_MILLIS = 10_000L
+    /**
+     * Parses every certificate from the bytes a CA-Issuers URL serves — a single DER certificate
+     * (e.g. Let's Encrypt), a PEM file, or a PKCS#7 "certs-only" bundle. Empty if the bytes are not
+     * parseable certificates.
+     */
+    fun parseCertificates(bytes: ByteArray): List<X509Certificate> =
+      try {
+        CertificateFactory.getInstance("X.509")
+          .generateCertificates(ByteArrayInputStream(bytes))
+          .filterIsInstance<X509Certificate>()
+      } catch (e: Exception) {
+        emptyList()
+      }
 
     /**
      * Reads [input] to EOF, or returns null once it exceeds [limit] bytes or [budgetMs] of
@@ -175,20 +350,6 @@ class CachingCertificateFetcher(
       }
     }
 
-    /**
-     * Parses every certificate from the bytes a CA-Issuers URL serves — a single DER certificate
-     * (e.g. Let's Encrypt), a PEM file, or a PKCS#7 "certs-only" bundle. Empty if the bytes are not
-     * parseable certificates.
-     */
-    fun parseCertificates(bytes: ByteArray): List<X509Certificate> =
-      try {
-        CertificateFactory.getInstance("X.509")
-          .generateCertificates(ByteArrayInputStream(bytes))
-          .filterIsInstance<X509Certificate>()
-      } catch (e: Exception) {
-        emptyList()
-      }
-
     /** Status code, `Location` header (if any), and decoded body of a raw HTTP response. */
     data class HttpResponse(val status: Int, val location: String?, val body: ByteArray)
 
@@ -231,7 +392,9 @@ class CachingCertificateFetcher(
             .substringBefore(';')
             .trim()
             .toIntOrNull(16) ?: break
-        if (size == 0) break // last chunk
+        // `<= 0`, not `== 0`: toIntOrNull accepts a leading `-`, and a negative size would move
+        // `pos` backwards — the same rewinding-cursor loop the DER reader had.
+        if (size <= 0) break // last chunk, or malformed
         val dataStart = eol + 2
         if (dataStart + size > body.size) break
         out.write(body, dataStart, size)

package/android/src/main/java/com/audiobrowser/util/BrowserPathHelper.kt

@@ -8,14 +8,19 @@ import java.net.URLEncoder
  * Utility for handling browser paths and contextual URLs in the media browser system.
  *
  * Handles two types of special paths:
- * 1. System paths (prefixed with `/__`): Root, recent, and search paths
+ * 1. System paths (prefixed with `/__`): root, search, offline, error, and gate paths
  * 2. Contextual URLs: Embed parent context in track identifiers for Media3 integration
  *
- * Contextual URL format: `{parentPath}?__trackId={trackSrc}` Example:
- * "/library/radio?__trackId=song.mp3"
+ * Contextual URL format: `{parentPath}?__trackId={trackIdentity}&__index={childIndex}` (the
+ * identity is the track's `id` when non-blank, else its `src`) Example:
+ * "/library/radio?__trackId=song.mp3&__index=2"
+ *
+ * `__trackId` is the identity check; `__index` (the child's position on the page at stamp time) is
+ * only a tie-breaker between surfaces that carry the same identity — a stale index never selects a
+ * different track.
  *
  * This allows:
- * - Media3 to reference playable-only tracks (tracks with `src` but no `url`)
+ * - Media3 to reference playable-only tracks (tracks with `src` but no `path`)
  * - Cache lookup to work consistently
  * - Parent context to be preserved for queue restoration
  */
@@ -23,9 +28,6 @@ object BrowserPathHelper {
   /** Root path for media browsing */
   const val ROOT_PATH = "/__root"
 
-  /** Recent media path for playback resumption */
-  const val RECENT_PATH = "/__recent"
-
   /** Search path prefix (full path is /__search?q=query) */
   const val SEARCH_PATH_PREFIX = "/__search"
 
@@ -41,9 +43,12 @@ object BrowserPathHelper {
   // Query parameter name for contextual track identifiers
   private const val CONTEXTUAL_TRACK_PARAM = "__trackId"
 
+  // Query parameter name for the tapped child's page position (tie-breaker)
+  private const val CONTEXTUAL_INDEX_PARAM = "__index"
+
   /** Check if a path is a special system path (not a regular navigation path) */
   fun isSpecialPath(path: String): Boolean {
-    return path == ROOT_PATH || path == RECENT_PATH || path.startsWith("$SEARCH_PATH_PREFIX?")
+    return path == ROOT_PATH || path.startsWith("$SEARCH_PATH_PREFIX?")
   }
 
   /** Create a search path for a given query */
@@ -63,13 +68,13 @@ object BrowserPathHelper {
   }
 
   /**
-   * Strips the __trackId parameter from a contextual URL to get the parent path. If the URL is not
-   * contextual, returns it unchanged.
+   * Strips the contextual parameters (__trackId and __index) from a contextual URL to get the
+   * parent path. If the URL is not contextual, returns it unchanged.
    *
    * @param url The URL to process
-   * @return The URL without the __trackId parameter
+   * @return The URL without the contextual parameters
    *
-   * Example: "/library/radio?__trackId=song.mp3" → "/library/radio" Example:
+   * Example: "/library/radio?__trackId=song.mp3&__index=2" → "/library/radio" Example:
    * "/search?q=jazz&__trackId=song.mp3" → "/search?q=jazz"
    */
   fun stripTrackId(url: String): String {
@@ -79,13 +84,13 @@ object BrowserPathHelper {
 
     val uri = url.toUri()
 
-    // Build URL preserving everything except __trackId parameter
+    // Build URL preserving everything except the contextual parameters
     val builder = uri.buildUpon()
     builder.clearQuery()
 
-    // Re-add all query params except __trackId
+    // Re-add all query params except __trackId and __index
     uri.queryParameterNames.forEach { paramName ->
-      if (paramName != CONTEXTUAL_TRACK_PARAM) {
+      if (paramName != CONTEXTUAL_TRACK_PARAM && paramName != CONTEXTUAL_INDEX_PARAM) {
         uri.getQueryParameters(paramName).forEach { value ->
           builder.appendQueryParameter(paramName, value)
         }
@@ -96,19 +101,21 @@ object BrowserPathHelper {
   }
 
   /**
-   * Builds a contextual URL by appending a track identifier to a parent path. Handles existing
-   * query parameters correctly.
+   * Builds a contextual URL by appending a track identifier — and optionally the tapped child's
+   * page position — to a parent path. Handles existing query parameters correctly.
    *
    * @param parentPath The parent container path
-   * @param trackId The track identifier (typically the `src` value)
-   * @return A contextual URL combining parent path and track ID
+   * @param trackId The track identity (`id` when non-blank, else `src` — see Track.identity)
+   * @param index The child's position on the page at stamp time (tie-breaker)
+   * @return A contextual URL combining parent path, track ID, and index
    *
-   * Example: build("/library", "song.mp3") → "/library?__trackId=song.mp3" Example:
+   * Example: build("/library", "song.mp3", 2) → "/library?__trackId=song.mp3&__index=2" Example:
    * build("/search?q=jazz", "song.mp3") → "/search?q=jazz&__trackId=song.mp3"
    */
-  fun build(parentPath: String, trackId: String): String {
+  fun build(parentPath: String, trackId: String, index: Int? = null): String {
     val separator = if (parentPath.contains('?')) '&' else '?'
-    return "$parentPath$separator$CONTEXTUAL_TRACK_PARAM=${Uri.encode(trackId)}"
+    val indexParam = if (index != null) "&$CONTEXTUAL_INDEX_PARAM=$index" else ""
+    return "$parentPath$separator$CONTEXTUAL_TRACK_PARAM=${Uri.encode(trackId)}$indexParam"
   }
 
   /**
@@ -129,6 +136,21 @@ object BrowserPathHelper {
     return uri.getQueryParameter(CONTEXTUAL_TRACK_PARAM)
   }
 
+  /**
+   * Extracts the stamped page index from a contextual URL, or null when the URL is not contextual
+   * or carries no (valid, non-negative) index.
+   *
+   * Example: "/library/radio?__trackId=song.mp3&__index=2" → 2
+   */
+  fun extractIndex(path: String): Int? {
+    if (!isContextual(path)) {
+      return null
+    }
+
+    val raw = Uri.parse(path).getQueryParameter(CONTEXTUAL_INDEX_PARAM) ?: return null
+    return raw.toIntOrNull()?.takeIf { it >= 0 }
+  }
+
   /**
    * Combines a base URL with a path, ensuring proper slash handling.
    *
@@ -158,22 +180,4 @@ object BrowserPathHelper {
     val normalizedPath = path.trimStart('/')
     return "$normalizedBase$normalizedPath"
   }
-
-  /**
-   * True if [segment] appears in [path] as a complete path segment — bounded on the left by the
-   * string start or `/`, and on the right by the string end or one of `/`, `?`, `#`.
-   */
-  fun containsSegment(path: String, segment: String): Boolean {
-    if (segment.isEmpty()) return false
-    var from = 0
-    while (true) {
-      val idx = path.indexOf(segment, from)
-      if (idx < 0) return false
-      val beforeOk = idx == 0 || path[idx - 1] == '/'
-      val end = idx + segment.length
-      val afterOk = end == path.length || path[end] == '/' || path[end] == '?' || path[end] == '#'
-      if (beforeOk && afterOk) return true
-      from = idx + 1
-    }
-  }
 }