react-native-audio-browser 0.1.1 → 0.2.0-next.2

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

@@ -0,0 +1,81 @@
+package com.audiobrowser.player
+
+import android.os.Handler
+import android.os.Looper
+import android.os.SystemClock
+
+/**
+ * Ramps the player volume down over a duration (sleep-timer fade). The gain follows a squared
+ * curve: loudness perception is logarithmic, so a linear gain ramp sounds like a late cutoff rather
+ * than a fade.
+ */
+class VolumeFader(private val getVolume: () -> Float, private val setVolume: (Float) -> Unit) {
+  private val handler = Handler(Looper.getMainLooper())
+  private var stepRunnable: Runnable? = null
+
+  /**
+   * Volume captured when the fade started; restored after the fade resolves. Non-null from fade
+   * start until cancel/completion, even once the ramp has reached silence.
+   */
+  var originalVolume: Float? = null
+    private set
+
+  val isActive: Boolean
+    get() = originalVolume != null
+
+  fun start(durationSeconds: Double) {
+    // If a fade is already running, keep its captured volume as the baseline — the current
+    // (partially faded) volume is not the value to restore.
+    val baseVolume = originalVolume ?: getVolume()
+    cancel(restoreVolume = false)
+    originalVolume = baseVolume
+    if (durationSeconds <= 0) return
+
+    val startTime = SystemClock.uptimeMillis()
+    val durationMs = durationSeconds * 1000
+    val runnable =
+      object : Runnable {
+        override fun run() {
+          val progress = ((SystemClock.uptimeMillis() - startTime) / durationMs).coerceAtMost(1.0)
+          val remaining = (1 - progress).toFloat()
+          setVolume(baseVolume * remaining * remaining)
+          if (progress < 1.0) {
+            handler.postDelayed(this, STEP_INTERVAL_MS)
+          } else {
+            stepRunnable = null
+          }
+        }
+      }
+    stepRunnable = runnable
+    handler.post(runnable)
+  }
+
+  /**
+   * Stops the ramp. With [restoreVolume] the pre-fade volume is put back immediately
+   * (cancellation); without it the caller restores after pausing (completion path — restoring first
+   * would let full-volume audio slip out).
+   */
+  fun cancel(restoreVolume: Boolean) {
+    stepRunnable?.let { handler.removeCallbacks(it) }
+    stepRunnable = null
+    val original = originalVolume ?: return
+    originalVolume = null
+    if (restoreVolume) setVolume(original)
+  }
+
+  /**
+   * Resolves the fade around a halting action: stops the ramp, runs [halt], then restores the
+   * pre-fade volume — in that order, because restoring before halting would let full-volume audio
+   * slip out. The restore is skipped when no fade was running.
+   */
+  fun resolve(halt: () -> Unit) {
+    val preFadeVolume = originalVolume
+    cancel(restoreVolume = false)
+    halt()
+    preFadeVolume?.let { setVolume(it) }
+  }
+
+  companion object {
+    private const val STEP_INTERVAL_MS = 50L
+  }
+}

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

@@ -0,0 +1,141 @@
+package com.audiobrowser.tls
+
+import java.security.cert.X509Certificate
+
+/**
+ * Fills in missing intermediate CA certificates by following the Authority Information Access (AIA)
+ * "CA Issuers" pointer in a certificate, the way Apple's Secure Transport does automatically but
+ * Android's default trust manager does not.
+ *
+ * Many servers (a common misconfiguration) present only their leaf certificate and omit the
+ * intermediate(s) needed to chain up to a trusted root. Browsers and iOS fetch the missing
+ * intermediate from the URL in the leaf's AIA extension; Android's `X509TrustManager` validates
+ * only what the server sent, so such streams fail with "Trust anchor for certification path not
+ * found".
+ */
+object AiaCertChaser {
+  /** Authority Information Access extension. */
+  private const val AIA_OID = "1.3.6.1.5.5.7.1.1"
+
+  /** DER-encoded OID value of id-ad-caIssuers (1.3.6.1.5.5.7.48.2). */
+  private val CA_ISSUERS_OID = byteArrayOf(0x2B, 0x06, 0x01, 0x05, 0x05, 0x07, 0x30, 0x02)
+
+  private const val TAG_SEQUENCE = 0x30
+  private const val TAG_OID = 0x06
+  private const val TAG_OCTET_STRING = 0x04
+
+  /**
+   * GeneralName.uniformResourceIdentifier = [6] IMPLICIT IA5String (context-specific, primitive).
+   */
+  private const val TAG_URI = 0x86
+
+  /**
+   * Returns the "CA Issuers" URLs from the certificate's AIA extension (the locations from which
+   * the issuing CA certificate can be fetched), or an empty list if the extension is absent or
+   * unparseable.
+   */
+  fun extractCaIssuerUrls(cert: X509Certificate): List<String> {
+    val raw = cert.getExtensionValue(AIA_OID) ?: return emptyList()
+    return try {
+      // getExtensionValue() returns the extension value wrapped in an OCTET STRING.
+      val wrapper = DerReader(raw).read()
+      if (wrapper.tag != TAG_OCTET_STRING) return emptyList()
+
+      // AuthorityInfoAccessSyntax ::= SEQUENCE OF AccessDescription
+      val aiaSeq = DerReader(wrapper.content()).read()
+      if (aiaSeq.tag != TAG_SEQUENCE) return emptyList()
+
+      val urls = mutableListOf<String>()
+      val descriptions = DerReader(aiaSeq.content())
+      while (descriptions.hasNext()) {
+        // AccessDescription ::= SEQUENCE { accessMethod OID, accessLocation GeneralName }
+        val desc = descriptions.read()
+        if (desc.tag != TAG_SEQUENCE) continue
+        val fields = DerReader(desc.content())
+        val method = fields.read()
+        if (method.tag != TAG_OID || !method.content().contentEquals(CA_ISSUERS_OID)) continue
+        if (!fields.hasNext()) continue
+        val location = fields.read()
+        if (location.tag == TAG_URI) {
+          urls.add(String(location.content(), Charsets.US_ASCII))
+        }
+      }
+      urls
+    } catch (e: Exception) {
+      // Malformed DER: treat as "no AIA" rather than crashing the handshake.
+      emptyList()
+    }
+  }
+
+  /**
+   * 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.
+   *
+   * 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
+   * accepted. From each URL's candidates the genuine issuer of the preceding certificate is
+   * selected (defends against an AIA pointer to an unrelated certificate, and picks the right one
+   * out of a multi-certificate PKCS#7 bundle).
+   *
+   * @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.
+   */
+  fun completeChain(
+    presented: List<X509Certificate>,
+    maxIntermediates: Int = 5,
+    fetch: (url: String) -> List<X509Certificate>,
+  ): List<X509Certificate> {
+    if (presented.isEmpty()) return presented
+    val chain = presented.toMutableList()
+    val seen = HashSet(chain)
+    var added = 0
+    while (added < maxIntermediates) {
+      val last = chain.last()
+      if (last.subjectX500Principal == last.issuerX500Principal) break // self-signed root
+      val issuer =
+        extractCaIssuerUrls(last)
+          .asSequence()
+          .flatMap { url -> runCatching { fetch(url) }.getOrElse { emptyList() } }
+          .firstOrNull { it.subjectX500Principal == last.issuerX500Principal } ?: break
+      if (!seen.add(issuer)) break // cycle guard
+      chain.add(issuer)
+      added++
+    }
+    return chain
+  }
+
+  /**
+   * 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".
+   */
+  private class DerReader(private val buf: ByteArray) {
+    private var pos = 0
+
+    fun hasNext(): Boolean = pos < buf.size
+
+    fun read(): Tlv {
+      val tag = buf[pos++].toInt() and 0xFF
+      var len = buf[pos++].toInt() and 0xFF
+      if (len and 0x80 != 0) {
+        val numBytes = len and 0x7F
+        len = 0
+        repeat(numBytes) { len = (len shl 8) or (buf[pos++].toInt() and 0xFF) }
+      }
+      val tlv = Tlv(buf, tag, pos, len)
+      pos += len
+      return tlv
+    }
+  }
+
+  /** A parsed tag-length-value: the tag and a view of its content bytes. */
+  private class Tlv(
+    private val buf: ByteArray,
+    val tag: Int,
+    private val offset: Int,
+    private val length: Int,
+  ) {
+    fun content(): ByteArray = buf.copyOfRange(offset, offset + length)
+  }
+}

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

@@ -0,0 +1,37 @@
+package com.audiobrowser.tls
+
+import java.security.cert.CertificateException
+import java.security.cert.X509Certificate
+import javax.net.ssl.X509TrustManager
+
+/**
+ * An [X509TrustManager] that retries validation after filling in missing intermediate certificates
+ * via the leaf's Authority Information Access (AIA) "CA Issuers" pointer.
+ *
+ * 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].
+ */
+class AiaChasingTrustManager(
+  private val delegate: X509TrustManager,
+  private val fetch: (url: String) -> 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)
+    }
+  }
+
+  override fun checkClientTrusted(chain: Array<X509Certificate>, authType: String) =
+    delegate.checkClientTrusted(chain, authType)
+
+  override fun getAcceptedIssuers(): Array<X509Certificate> = delegate.acceptedIssuers
+}

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

@@ -0,0 +1,41 @@
+package com.audiobrowser.tls
+
+import java.security.KeyStore
+import javax.net.ssl.SSLContext
+import javax.net.ssl.SSLSocketFactory
+import javax.net.ssl.TrustManagerFactory
+import javax.net.ssl.X509TrustManager
+
+/**
+ * Builds TLS components that recover from servers which omit intermediate CA certificates, by
+ * 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.
+ */
+object AiaTls {
+
+  /**
+   * An [SSLSocketFactory] whose handshake validation chases missing intermediates via AIA. Intended
+   * to be built once (e.g. installed as the process default at startup); each call gets its own
+   * fetched-intermediate cache.
+   */
+  fun socketFactory(): SSLSocketFactory =
+    SSLContext.getInstance("TLS").apply { init(null, arrayOf(trustManager()), null) }.socketFactory
+
+  /** An [X509TrustManager] wrapping the platform default with AIA intermediate chasing. */
+  fun trustManager(): X509TrustManager {
+    val fetcher = CachingCertificateFetcher()
+    return AiaChasingTrustManager(systemTrustManager()) { fetcher.fetch(it) }
+  }
+
+  private fun systemTrustManager(): X509TrustManager {
+    val factory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm())
+    factory.init(null as KeyStore?)
+    return factory.trustManagers.filterIsInstance<X509TrustManager>().first()
+  }
+}

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

@@ -0,0 +1,209 @@
+package com.audiobrowser.tls
+
+import java.io.ByteArrayInputStream
+import java.io.ByteArrayOutputStream
+import java.net.InetSocketAddress
+import java.net.Socket
+import java.net.URL
+import java.security.cert.CertificateFactory
+import java.security.cert.X509Certificate
+import java.util.concurrent.ConcurrentHashMap
+import javax.net.ssl.HttpsURLConnection
+import javax.net.ssl.SSLContext
+import javax.net.ssl.SSLSocketFactory
+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.
+ *
+ * `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.
+ */
+class CachingCertificateFetcher(
+  private val connectTimeoutMs: Int = 5_000,
+  private val readTimeoutMs: Int = 5_000,
+) {
+  private val cache = ConcurrentHashMap<String, List<X509Certificate>>()
+
+  /**
+   * A plain system-default socket factory for `https` AIA fetches. Without it the fetch would use
+   * the process default — which, once this library's AIA factory is installed there, would recurse
+   * into AIA chasing during the fetch's own handshake.
+   */
+  private val plainSslSocketFactory: SSLSocketFactory by lazy {
+    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
+    return certs
+  }
+
+  private fun download(url: String, redirectsLeft: Int = MAX_REDIRECTS): ByteArray? =
+    try {
+      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
+      }
+    } catch (e: Exception) {
+      Timber.w(e, "AIA CA-issuer fetch failed: %s", 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.
+   */
+  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 { it.readBytes() }
+  }
+
+  /**
+   * `http` AIA fetch over a raw socket — see the class doc for why this bypasses
+   * `HttpURLConnection`.
+   */
+  private fun downloadCleartext(url: URL, redirectsLeft: Int): ByteArray? {
+    val host = url.host
+    val port = if (url.port != -1) url.port else 80
+    val path = url.file.ifEmpty { "/" } // URL.file is path + query
+    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()
+        }
+        socket.getInputStream().use { it.readBytes() }
+      }
+    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)
+      else -> null
+    }
+  }
+
+  companion object {
+    private const val MAX_REDIRECTS = 5
+
+    /**
+     * 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)
+
+    /**
+     * Splits a raw HTTP/1.0 response into its status code, `Location` header, and body, decoding a
+     * `Transfer-Encoding: chunked` body if present. Returns null if the bytes are not a
+     * recognisable HTTP response.
+     */
+    fun parseHttpResponse(raw: ByteArray): HttpResponse? {
+      val headerEnd = indexOfCrlfCrlf(raw)
+      if (headerEnd < 0) return null
+      val lines = String(raw, 0, headerEnd, Charsets.ISO_8859_1).split("\r\n")
+      // Status line: "HTTP/1.1 200 OK" — the code is the second token.
+      val status = lines.firstOrNull()?.split(' ')?.getOrNull(1)?.toIntOrNull() ?: return null
+      var location: String? = null
+      var chunked = false
+      for (i in 1 until lines.size) {
+        val colon = lines[i].indexOf(':')
+        if (colon < 0) continue
+        val name = lines[i].substring(0, colon).trim().lowercase()
+        val value = lines[i].substring(colon + 1).trim()
+        when (name) {
+          "location" -> location = value
+          "transfer-encoding" -> if (value.lowercase().contains("chunked")) chunked = true
+        }
+      }
+      val body = raw.copyOfRange(headerEnd + 4, raw.size)
+      return HttpResponse(status, location, if (chunked) dechunk(body) else body)
+    }
+
+    private fun dechunk(body: ByteArray): ByteArray {
+      val out = ByteArrayOutputStream()
+      var pos = 0
+      while (pos < body.size) {
+        val eol = indexOfCrlf(body, pos)
+        if (eol < 0) break
+        // chunk-size line may carry a `;chunk-extension` suffix; the size is hex before the `;`.
+        val size =
+          String(body, pos, eol - pos, Charsets.ISO_8859_1)
+            .substringBefore(';')
+            .trim()
+            .toIntOrNull(16) ?: break
+        if (size == 0) break // last chunk
+        val dataStart = eol + 2
+        if (dataStart + size > body.size) break
+        out.write(body, dataStart, size)
+        pos = dataStart + size + 2 // skip the chunk data and its trailing CRLF
+      }
+      return out.toByteArray()
+    }
+
+    private fun indexOfCrlfCrlf(bytes: ByteArray): Int {
+      var i = 0
+      while (i + 3 < bytes.size) {
+        if (bytes[i] == CR && bytes[i + 1] == LF && bytes[i + 2] == CR && bytes[i + 3] == LF)
+          return i
+        i++
+      }
+      return -1
+    }
+
+    private fun indexOfCrlf(bytes: ByteArray, from: Int): Int {
+      var i = from
+      while (i + 1 < bytes.size) {
+        if (bytes[i] == CR && bytes[i + 1] == LF) return i
+        i++
+      }
+      return -1
+    }
+
+    private const val CR = '\r'.code.toByte()
+    private const val LF = '\n'.code.toByte()
+  }
+}

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

@@ -0,0 +1,161 @@
+package com.audiobrowser.util
+
+import android.content.ContentProvider
+import android.content.ContentValues
+import android.database.Cursor
+import android.graphics.Bitmap
+import android.net.Uri
+import android.os.ParcelFileDescriptor
+import com.audiobrowser.browser.ResolvedArtwork
+import java.io.File
+import java.io.IOException
+import java.util.concurrent.Semaphore
+import java.util.concurrent.TimeUnit
+import kotlinx.coroutines.runBlocking
+import kotlinx.coroutines.withTimeout
+import timber.log.Timber
+
+/**
+ * Exported, token-gated provider serving browse artwork to Android Auto / AAOS (which run in a
+ * different uid and cannot read a non-exported provider; Media3 issues no URI grant — verified). It
+ * NEVER fetches a caller-supplied URL: the content URI carries an opaque token, looked up in
+ * [com.audiobrowser.browser.BrowseArtworkRegistry]; an unknown token returns null. So it cannot be
+ * used as a fetch proxy / SSRF vector. http(s)-only on the registered finalUrl is defense-in-depth.
+ *
+ * Serve design: a real on-disk file via [ParcelFileDescriptor.open] — seekable, no pipe, no writer
+ * coroutine. The file is keyed by SHA-256 token so identical URLs always reuse the same file.
+ *
+ * Bug fixes over the previous pipe/coroutine design: B (FD leak): eliminated — no coroutine
+ * launched from deps.scope; no writer that could fail to close the write-end of a pipe when the
+ * scope is already cancelled. C (wedge DoS): eliminated — the Semaphore permit is released in a
+ * try/finally BEFORE the file is opened for the caller; no blocking write to a pipe while holding
+ * the permit. D (per-request re-encode): eliminated — on-disk file IS the cache; re-requests are a
+ * cheap file open (fast path, zero decode, zero network). E (non-seekable pipe): eliminated —
+ * ParcelFileDescriptor.open returns a regular file FD; statSize is valid; the car's image loader
+ * can seek.
+ */
+class ArtworkContentProvider : ContentProvider() {
+
+  // java.util.concurrent.Semaphore — works on binder threads without a coroutine scope.
+  private val gate = Semaphore(MAX_CONCURRENT)
+
+  override fun onCreate(): Boolean = true
+
+  override fun getType(uri: Uri): String = "image/png"
+
+  override fun openFile(uri: Uri, mode: String): ParcelFileDescriptor? {
+    val token = ArtworkUris.parseToken(uri) ?: return null
+    val deps = CoilArtworkLoaderHolder.get() ?: return null
+    val art: ResolvedArtwork = deps.registry.lookup(token) ?: return null
+    val scheme = Uri.parse(art.finalUrl).scheme?.lowercase()
+    if (scheme != "http" && scheme != "https") return null
+
+    val artworkDir = File(context!!.cacheDir, ARTWORK_SUBDIR)
+    val file = File(artworkDir, "$token.png")
+
+    // Fast path: file already cached on disk — no permit, no decode, no network.
+    if (file.exists() && file.length() > 0) {
+      return try {
+        ParcelFileDescriptor.open(file, ParcelFileDescriptor.MODE_READ_ONLY)
+      } catch (e: Throwable) {
+        Timber.w(e, "Artwork fast-path open failed for token=$token")
+        null
+      }
+    }
+
+    // Produce path (cache miss): bound concurrency, block on binder thread (UAMP pattern).
+    if (!gate.tryAcquire(1, GATE_TIMEOUT_SECONDS, TimeUnit.SECONDS)) {
+      Timber.w("Artwork gate timeout for token=$token — returning null")
+      return null
+    }
+    try {
+      // Re-check after acquiring — a concurrent producer may have written the file.
+      if (file.exists() && file.length() > 0) {
+        val fd =
+          try {
+            ParcelFileDescriptor.open(file, ParcelFileDescriptor.MODE_READ_ONLY)
+          } catch (e: Throwable) {
+            Timber.w(e, "Artwork cache file vanished before re-check open; producing")
+            null
+          }
+        if (fd != null) return fd
+        // else: file was pruned/deleted concurrently — fall through to produce
+      }
+
+      artworkDir.mkdirs()
+      val tmp = File.createTempFile(token, ".png.tmp", artworkDir)
+
+      val bitmap: Bitmap =
+        try {
+          runBlocking {
+            withTimeout(LOAD_TIMEOUT_MS) {
+              deps.loader.load(art.finalUrl, art.headers, deps.artworkSizeHint(), art.isSvg)
+            }
+          }
+        } catch (e: Throwable) {
+          Timber.w(e, "Artwork load failed for token=$token")
+          tmp.delete()
+          return null
+        }
+
+      try {
+        val ok =
+          tmp.outputStream().use { out -> bitmap.compress(Bitmap.CompressFormat.PNG, 100, out) }
+        if (!ok) throw IOException("PNG encode failed for token=$token")
+        if (!tmp.renameTo(file)) {
+          Timber.w("Artwork rename failed for token=$token")
+          tmp.delete()
+          return null
+        }
+        pruneCache(artworkDir)
+      } catch (e: Throwable) {
+        Timber.w(e, "Artwork write failed for token=$token")
+        tmp.delete()
+        return null
+      }
+
+      return try {
+        ParcelFileDescriptor.open(file, ParcelFileDescriptor.MODE_READ_ONLY)
+      } catch (e: Throwable) {
+        Timber.w(e, "Artwork final open failed for token=$token")
+        null
+      }
+    } finally {
+      gate.release()
+    }
+  }
+
+  override fun query(
+    uri: Uri,
+    p: Array<String>?,
+    s: String?,
+    a: Array<String>?,
+    o: String?,
+  ): Cursor? = null
+
+  override fun insert(uri: Uri, values: ContentValues?): Uri? = null
+
+  override fun update(uri: Uri, v: ContentValues?, s: String?, a: Array<String>?): Int = 0
+
+  override fun delete(uri: Uri, s: String?, a: Array<String>?): Int = 0
+
+  companion object {
+    private const val MAX_CONCURRENT = 6
+    private const val GATE_TIMEOUT_SECONDS = 5L
+    private const val LOAD_TIMEOUT_MS = 8_000L
+    internal const val ARTWORK_SUBDIR = "audiobrowser-artwork"
+    const val MAX_CACHE_FILES = 512
+    /** Overridable in tests only. Production code must not change this. */
+    @JvmField internal var maxCacheFilesOverride: Int? = null
+  }
+
+  private fun pruneCache(dir: File) {
+    val limit = maxCacheFilesOverride ?: MAX_CACHE_FILES
+    val files = dir.listFiles { f -> f.isFile && f.name.endsWith(".png") } ?: return
+    if (files.size <= limit) return
+    files
+      .sortedBy { it.lastModified() }
+      .take(files.size - limit)
+      .forEach { runCatching { it.delete() } }
+  }
+}