react-native-audio-browser 0.2.0-next.54 → 0.2.0-next.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (271) hide show
  1. package/README.md +32 -19
  2. package/lib/commonjs/CLAUDE.md +7 -2
  3. package/lib/commonjs/features/battery.js +16 -12
  4. package/lib/commonjs/features/battery.js.map +1 -1
  5. package/lib/commonjs/features/browser-config.js +1 -1
  6. package/lib/commonjs/features/browser.js +74 -24
  7. package/lib/commonjs/features/browser.js.map +1 -1
  8. package/lib/commonjs/features/carConnection.js +3 -4
  9. package/lib/commonjs/features/carConnection.js.map +1 -1
  10. package/lib/commonjs/features/equalizer.js +9 -5
  11. package/lib/commonjs/features/equalizer.js.map +1 -1
  12. package/lib/commonjs/features/errors.js +35 -21
  13. package/lib/commonjs/features/errors.js.map +1 -1
  14. package/lib/commonjs/features/favorites.js +15 -13
  15. package/lib/commonjs/features/favorites.js.map +1 -1
  16. package/lib/commonjs/features/gate.js +12 -6
  17. package/lib/commonjs/features/gate.js.map +1 -1
  18. package/lib/commonjs/features/metadata.js +16 -14
  19. package/lib/commonjs/features/metadata.js.map +1 -1
  20. package/lib/commonjs/features/network.js +5 -1
  21. package/lib/commonjs/features/network.js.map +1 -1
  22. package/lib/commonjs/features/nowPlaying.js +28 -14
  23. package/lib/commonjs/features/nowPlaying.js.map +1 -1
  24. package/lib/commonjs/features/output.js +8 -4
  25. package/lib/commonjs/features/output.js.map +1 -1
  26. package/lib/commonjs/features/playback/controls.js +10 -5
  27. package/lib/commonjs/features/playback/controls.js.map +1 -1
  28. package/lib/commonjs/features/playback/playWhenReady.js +6 -5
  29. package/lib/commonjs/features/playback/playWhenReady.js.map +1 -1
  30. package/lib/commonjs/features/playback/playing.js +5 -3
  31. package/lib/commonjs/features/playback/playing.js.map +1 -1
  32. package/lib/commonjs/features/playback/progress.js +11 -5
  33. package/lib/commonjs/features/playback/progress.js.map +1 -1
  34. package/lib/commonjs/features/playback/state.js +3 -3
  35. package/lib/commonjs/features/playback/state.js.map +1 -1
  36. package/lib/commonjs/features/playback/trackPlaybackTime.js +6 -1
  37. package/lib/commonjs/features/playback/trackPlaybackTime.js.map +1 -1
  38. package/lib/commonjs/features/playback/volume.js +6 -5
  39. package/lib/commonjs/features/playback/volume.js.map +1 -1
  40. package/lib/commonjs/features/player/options.js +20 -10
  41. package/lib/commonjs/features/player/options.js.map +1 -1
  42. package/lib/commonjs/features/player/setup.js +34 -38
  43. package/lib/commonjs/features/player/setup.js.map +1 -1
  44. package/lib/commonjs/features/queue/activeTrack.js +0 -1
  45. package/lib/commonjs/features/queue/activeTrack.js.map +1 -1
  46. package/lib/commonjs/features/queue/queue.js +48 -20
  47. package/lib/commonjs/features/queue/queue.js.map +1 -1
  48. package/lib/commonjs/features/queue/repeatMode.js +2 -1
  49. package/lib/commonjs/features/queue/repeatMode.js.map +1 -1
  50. package/lib/commonjs/features/queue/shuffle.js +0 -1
  51. package/lib/commonjs/features/queue/shuffle.js.map +1 -1
  52. package/lib/commonjs/features/remoteControls.js +59 -35
  53. package/lib/commonjs/features/remoteControls.js.map +1 -1
  54. package/lib/commonjs/features/sleepTimer.js +15 -6
  55. package/lib/commonjs/features/sleepTimer.js.map +1 -1
  56. package/lib/commonjs/utils/LazyNativeEmitter.js +6 -9
  57. package/lib/commonjs/utils/LazyNativeEmitter.js.map +1 -1
  58. package/lib/commonjs/utils/NativeUpdatedValue.js +13 -12
  59. package/lib/commonjs/utils/NativeUpdatedValue.js.map +1 -1
  60. package/lib/commonjs/utils/getTrackIdentity.js +6 -4
  61. package/lib/commonjs/utils/getTrackIdentity.js.map +1 -1
  62. package/lib/commonjs/utils/useDebug.js +16 -3
  63. package/lib/commonjs/utils/useDebug.js.map +1 -1
  64. package/lib/commonjs/web/NativeAudioBrowser.js +2 -4
  65. package/lib/commonjs/web/NativeAudioBrowser.js.map +1 -1
  66. package/lib/commonjs/web/browser/parseSearchResponse.js +3 -4
  67. package/lib/commonjs/web/browser/parseSearchResponse.js.map +1 -1
  68. package/lib/commonjs/web/browser/sections.js +1 -1
  69. package/lib/commonjs/web/util/BrowserPathHelper.js +1 -3
  70. package/lib/commonjs/web/util/BrowserPathHelper.js.map +1 -1
  71. package/lib/module/CLAUDE.md +7 -2
  72. package/lib/module/features/battery.js +16 -12
  73. package/lib/module/features/battery.js.map +1 -1
  74. package/lib/module/features/browser-config.js +1 -1
  75. package/lib/module/features/browser.js +74 -24
  76. package/lib/module/features/browser.js.map +1 -1
  77. package/lib/module/features/carConnection.js +3 -4
  78. package/lib/module/features/carConnection.js.map +1 -1
  79. package/lib/module/features/equalizer.js +9 -5
  80. package/lib/module/features/equalizer.js.map +1 -1
  81. package/lib/module/features/errors.js +35 -21
  82. package/lib/module/features/errors.js.map +1 -1
  83. package/lib/module/features/favorites.js +15 -13
  84. package/lib/module/features/favorites.js.map +1 -1
  85. package/lib/module/features/gate.js +12 -6
  86. package/lib/module/features/gate.js.map +1 -1
  87. package/lib/module/features/metadata.js +16 -14
  88. package/lib/module/features/metadata.js.map +1 -1
  89. package/lib/module/features/network.js +5 -1
  90. package/lib/module/features/network.js.map +1 -1
  91. package/lib/module/features/nowPlaying.js +28 -14
  92. package/lib/module/features/nowPlaying.js.map +1 -1
  93. package/lib/module/features/output.js +8 -4
  94. package/lib/module/features/output.js.map +1 -1
  95. package/lib/module/features/playback/controls.js +10 -5
  96. package/lib/module/features/playback/controls.js.map +1 -1
  97. package/lib/module/features/playback/playWhenReady.js +6 -5
  98. package/lib/module/features/playback/playWhenReady.js.map +1 -1
  99. package/lib/module/features/playback/playing.js +5 -3
  100. package/lib/module/features/playback/playing.js.map +1 -1
  101. package/lib/module/features/playback/progress.js +11 -5
  102. package/lib/module/features/playback/progress.js.map +1 -1
  103. package/lib/module/features/playback/state.js +3 -3
  104. package/lib/module/features/playback/state.js.map +1 -1
  105. package/lib/module/features/playback/trackPlaybackTime.js +6 -1
  106. package/lib/module/features/playback/trackPlaybackTime.js.map +1 -1
  107. package/lib/module/features/playback/volume.js +6 -5
  108. package/lib/module/features/playback/volume.js.map +1 -1
  109. package/lib/module/features/player/options.js +20 -10
  110. package/lib/module/features/player/options.js.map +1 -1
  111. package/lib/module/features/player/setup.js +34 -38
  112. package/lib/module/features/player/setup.js.map +1 -1
  113. package/lib/module/features/queue/activeTrack.js +0 -1
  114. package/lib/module/features/queue/activeTrack.js.map +1 -1
  115. package/lib/module/features/queue/queue.js +48 -20
  116. package/lib/module/features/queue/queue.js.map +1 -1
  117. package/lib/module/features/queue/repeatMode.js +2 -1
  118. package/lib/module/features/queue/repeatMode.js.map +1 -1
  119. package/lib/module/features/queue/shuffle.js +0 -1
  120. package/lib/module/features/queue/shuffle.js.map +1 -1
  121. package/lib/module/features/remoteControls.js +59 -35
  122. package/lib/module/features/remoteControls.js.map +1 -1
  123. package/lib/module/features/sleepTimer.js +15 -6
  124. package/lib/module/features/sleepTimer.js.map +1 -1
  125. package/lib/module/utils/LazyNativeEmitter.js +6 -9
  126. package/lib/module/utils/LazyNativeEmitter.js.map +1 -1
  127. package/lib/module/utils/NativeUpdatedValue.js +13 -12
  128. package/lib/module/utils/NativeUpdatedValue.js.map +1 -1
  129. package/lib/module/utils/getTrackIdentity.js +6 -4
  130. package/lib/module/utils/getTrackIdentity.js.map +1 -1
  131. package/lib/module/utils/useDebug.js +16 -3
  132. package/lib/module/utils/useDebug.js.map +1 -1
  133. package/lib/module/web/NativeAudioBrowser.js +2 -4
  134. package/lib/module/web/NativeAudioBrowser.js.map +1 -1
  135. package/lib/module/web/browser/parseSearchResponse.js +3 -4
  136. package/lib/module/web/browser/parseSearchResponse.js.map +1 -1
  137. package/lib/module/web/browser/sections.js +1 -1
  138. package/lib/module/web/util/BrowserPathHelper.js +1 -3
  139. package/lib/module/web/util/BrowserPathHelper.js.map +1 -1
  140. package/lib/typescript/src/features/battery.d.ts +17 -12
  141. package/lib/typescript/src/features/battery.d.ts.map +1 -1
  142. package/lib/typescript/src/features/browser.d.ts +64 -24
  143. package/lib/typescript/src/features/browser.d.ts.map +1 -1
  144. package/lib/typescript/src/features/carConnection.d.ts +3 -4
  145. package/lib/typescript/src/features/carConnection.d.ts.map +1 -1
  146. package/lib/typescript/src/features/equalizer.d.ts +9 -5
  147. package/lib/typescript/src/features/equalizer.d.ts.map +1 -1
  148. package/lib/typescript/src/features/errors.d.ts +37 -22
  149. package/lib/typescript/src/features/errors.d.ts.map +1 -1
  150. package/lib/typescript/src/features/favorites.d.ts +15 -13
  151. package/lib/typescript/src/features/favorites.d.ts.map +1 -1
  152. package/lib/typescript/src/features/gate.d.ts +14 -8
  153. package/lib/typescript/src/features/gate.d.ts.map +1 -1
  154. package/lib/typescript/src/features/metadata.d.ts +37 -17
  155. package/lib/typescript/src/features/metadata.d.ts.map +1 -1
  156. package/lib/typescript/src/features/network.d.ts +5 -1
  157. package/lib/typescript/src/features/network.d.ts.map +1 -1
  158. package/lib/typescript/src/features/nowPlaying.d.ts +28 -14
  159. package/lib/typescript/src/features/nowPlaying.d.ts.map +1 -1
  160. package/lib/typescript/src/features/output.d.ts +8 -4
  161. package/lib/typescript/src/features/output.d.ts.map +1 -1
  162. package/lib/typescript/src/features/playback/controls.d.ts +10 -5
  163. package/lib/typescript/src/features/playback/controls.d.ts.map +1 -1
  164. package/lib/typescript/src/features/playback/playWhenReady.d.ts +6 -5
  165. package/lib/typescript/src/features/playback/playWhenReady.d.ts.map +1 -1
  166. package/lib/typescript/src/features/playback/playing.d.ts +16 -3
  167. package/lib/typescript/src/features/playback/playing.d.ts.map +1 -1
  168. package/lib/typescript/src/features/playback/progress.d.ts +11 -5
  169. package/lib/typescript/src/features/playback/progress.d.ts.map +1 -1
  170. package/lib/typescript/src/features/playback/state.d.ts +8 -3
  171. package/lib/typescript/src/features/playback/state.d.ts.map +1 -1
  172. package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts +9 -2
  173. package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts.map +1 -1
  174. package/lib/typescript/src/features/playback/volume.d.ts +6 -5
  175. package/lib/typescript/src/features/playback/volume.d.ts.map +1 -1
  176. package/lib/typescript/src/features/player/options.d.ts +52 -37
  177. package/lib/typescript/src/features/player/options.d.ts.map +1 -1
  178. package/lib/typescript/src/features/player/setup.d.ts +65 -60
  179. package/lib/typescript/src/features/player/setup.d.ts.map +1 -1
  180. package/lib/typescript/src/features/queue/activeTrack.d.ts +0 -1
  181. package/lib/typescript/src/features/queue/activeTrack.d.ts.map +1 -1
  182. package/lib/typescript/src/features/queue/queue.d.ts +48 -20
  183. package/lib/typescript/src/features/queue/queue.d.ts.map +1 -1
  184. package/lib/typescript/src/features/queue/repeatMode.d.ts +1 -1
  185. package/lib/typescript/src/features/queue/repeatMode.d.ts.map +1 -1
  186. package/lib/typescript/src/features/queue/shuffle.d.ts +0 -1
  187. package/lib/typescript/src/features/queue/shuffle.d.ts.map +1 -1
  188. package/lib/typescript/src/features/remoteControls.d.ts +58 -25
  189. package/lib/typescript/src/features/remoteControls.d.ts.map +1 -1
  190. package/lib/typescript/src/features/sleepTimer.d.ts +15 -7
  191. package/lib/typescript/src/features/sleepTimer.d.ts.map +1 -1
  192. package/lib/typescript/src/types/browser-nodes.d.ts +54 -57
  193. package/lib/typescript/src/types/browser-nodes.d.ts.map +1 -1
  194. package/lib/typescript/src/types/browser.d.ts +181 -144
  195. package/lib/typescript/src/types/browser.d.ts.map +1 -1
  196. package/lib/typescript/src/utils/LazyNativeEmitter.d.ts +6 -9
  197. package/lib/typescript/src/utils/LazyNativeEmitter.d.ts.map +1 -1
  198. package/lib/typescript/src/utils/NativeUpdatedValue.d.ts +13 -12
  199. package/lib/typescript/src/utils/NativeUpdatedValue.d.ts.map +1 -1
  200. package/lib/typescript/src/utils/getTrackIdentity.d.ts +6 -4
  201. package/lib/typescript/src/utils/getTrackIdentity.d.ts.map +1 -1
  202. package/lib/typescript/src/utils/useDebug.d.ts +16 -3
  203. package/lib/typescript/src/utils/useDebug.d.ts.map +1 -1
  204. package/package.json +1 -1
  205. package/src/CLAUDE.md +7 -2
  206. package/src/docs-floors.test.ts +71 -0
  207. package/src/features/battery.ts +17 -13
  208. package/src/features/browser-config.ts +1 -1
  209. package/src/features/browser.ts +65 -24
  210. package/src/features/carConnection.ts +3 -4
  211. package/src/features/equalizer.ts +9 -5
  212. package/src/features/errors.ts +37 -22
  213. package/src/features/favorites.ts +15 -13
  214. package/src/features/gate.ts +14 -8
  215. package/src/features/metadata.ts +37 -17
  216. package/src/features/network.ts +5 -1
  217. package/src/features/nowPlaying.ts +28 -14
  218. package/src/features/output.ts +8 -4
  219. package/src/features/playback/controls.ts +10 -5
  220. package/src/features/playback/playWhenReady.ts +6 -5
  221. package/src/features/playback/playing.ts +16 -3
  222. package/src/features/playback/progress.ts +11 -5
  223. package/src/features/playback/state.ts +8 -3
  224. package/src/features/playback/trackPlaybackTime.ts +9 -2
  225. package/src/features/playback/volume.ts +6 -5
  226. package/src/features/player/options.ts +54 -43
  227. package/src/features/player/setup.ts +67 -61
  228. package/src/features/queue/activeTrack.ts +0 -1
  229. package/src/features/queue/queue.ts +48 -20
  230. package/src/features/queue/repeatMode.ts +1 -1
  231. package/src/features/queue/shuffle.ts +0 -1
  232. package/src/features/remoteControls.ts +59 -35
  233. package/src/features/sleepTimer.ts +15 -7
  234. package/src/types/browser-nodes.ts +54 -57
  235. package/src/types/browser.ts +183 -146
  236. package/src/utils/LazyNativeEmitter.ts +6 -9
  237. package/src/utils/NativeUpdatedValue.ts +13 -12
  238. package/src/utils/getTrackIdentity.ts +6 -4
  239. package/src/utils/useDebug.ts +16 -3
  240. package/src/web/NativeAudioBrowser.ts +2 -4
  241. package/src/web/browser/parseSearchResponse.ts +3 -4
  242. package/src/web/browser/sections.ts +1 -1
  243. package/src/web/util/BrowserPathHelper.ts +1 -3
  244. package/website/guide/android-auto.md +25 -13
  245. package/website/guide/android-certificates.md +199 -120
  246. package/website/guide/artwork.md +93 -48
  247. package/website/guide/audio-output.md +86 -68
  248. package/website/guide/automotive.md +15 -10
  249. package/website/guide/basic-usage.md +5 -2
  250. package/website/guide/battery.md +50 -23
  251. package/website/guide/browser.md +155 -68
  252. package/website/guide/carplay.md +132 -49
  253. package/website/guide/configuration.md +85 -49
  254. package/website/guide/equalizer.md +36 -32
  255. package/website/guide/errors.md +106 -64
  256. package/website/guide/favorites.md +41 -31
  257. package/website/guide/gate.md +24 -10
  258. package/website/guide/getting-started.md +55 -2
  259. package/website/guide/hooks.md +53 -47
  260. package/website/guide/live-streams.md +80 -49
  261. package/website/guide/metadata.md +87 -53
  262. package/website/guide/migrating-from-track-player.md +94 -49
  263. package/website/guide/native-callback-fetch.md +46 -36
  264. package/website/guide/network.md +36 -20
  265. package/website/guide/now-playing.md +72 -44
  266. package/website/guide/playback.md +112 -35
  267. package/website/guide/queue.md +77 -43
  268. package/website/guide/remote-controls.md +87 -29
  269. package/website/guide/search.md +37 -22
  270. package/website/guide/sleep-timer.md +35 -14
  271. package/website/guide/track.md +59 -35
@@ -1,16 +1,23 @@
1
1
  ---
2
- description: 'Fix Android SSLHandshakeException / "Trust anchor for certification path not found" on HTTPS streams whose server omits its intermediate certificate.'
2
+ description: 'Why Android playback fails with SSLHandshakeException / "Trust anchor for certification path not found" on HTTPS streams whose server omits its intermediate certificate, and what the AIA toolkit does and does not reach.'
3
3
  ---
4
4
 
5
- # Android: SSL "Trust anchor for certification path not found" (missing intermediate certificates)
5
+ # Android: missing intermediate certificates
6
6
 
7
- **If Android playback of a radio stream (or any HTTPS audio source) fails with an
8
- `SSLHandshakeException` / `CertPathValidatorException` / "Trust anchor for
9
- certification path not found" — and the same stream plays fine on iOS and in a
10
- desktop browser — you are in the right place.** This is almost always a server
11
- that omits an intermediate certificate; the fix is to let the client chase the
12
- missing certificate via the leaf's Authority Information Access (AIA) pointer, and
13
- this guide shows the one-time Android setup that does it.
7
+ Android playback of an HTTPS stream can fail with `SSLHandshakeException`,
8
+ `CertPathValidatorException` or "Trust anchor for certification path not found"
9
+ while the same stream plays on iOS and in a desktop browser. The cause is almost
10
+ always a server that omits an intermediate certificate.
11
+
12
+ The library ships `AiaTls`, a toolkit that fetches the missing certificate from
13
+ the URL in the leaf's Authority Information Access (AIA) extension. It does not
14
+ reach playback (see [The problem](#the-problem)), so installing `AiaTls` does
15
+ not fix a failing stream.
16
+
17
+ The reliable fix is for the server to send its full chain. The client-side
18
+ alternative is a Network Security Config that trusts the missing intermediate (see
19
+ [Fix playback from the app](#fix-playback-from-the-app)). This guide shows how
20
+ to confirm the diagnosis, and where `AiaTls` does apply.
14
21
 
15
22
  ## The problem
16
23
 
@@ -31,17 +38,23 @@ client to find the gap on its own.
31
38
  Trust anchor for certification path not found.
32
39
  ```
33
40
 
34
- This affects media playback because the Android player transports audio over
35
- `HttpURLConnection`, which uses the process-wide default `SSLSocketFactory`.
41
+ The player sends media over its own OkHttp client, which validates with the
42
+ platform default trust manager. OkHttp does not read the process-wide default
43
+ `SSLSocketFactory`, and the library offers no way to give that client another
44
+ one.
45
+
46
+ Nothing the app sets as a socket factory reaches playback. Only a Network
47
+ Security Config does, because the platform trust manager reads it.
36
48
 
37
49
  > **iOS needs no setup.** Apple's TLS stack chases AIA intermediates on its own,
38
50
  > so there is nothing to configure on iOS — this guide is Android-only.
39
51
 
40
52
  ## Is this actually your problem?
41
53
 
42
- Before changing process-global TLS state, confirm the failing stream really is a
43
- missing-intermediate case and not some other TLS failure (an expired cert, an SNI
44
- mismatch, or a genuinely untrusted root — none of which this fix addresses).
54
+ Before you report the stream to its operator or change TLS state, confirm the
55
+ failing stream really is a missing-intermediate case. Other TLS failures look
56
+ alike: an expired cert, an SNI mismatch, or a genuinely untrusted root.
57
+ `AiaTls` addresses none of them.
45
58
 
46
59
  Run, against your failing stream's **host** — use just the hostname, not the full
47
60
  stream URL. If your stream URL is `https://example.com:8000/live.mp3`, the host is
@@ -53,6 +66,15 @@ openssl s_client -connect example.com:443 \
53
66
  -servername example.com -showcerts </dev/null
54
67
  ```
55
68
 
69
+ This command does not decode the leaf's extensions. To see its AIA pointer,
70
+ decode the leaf:
71
+
72
+ ```sh
73
+ openssl s_client -connect example.com:443 \
74
+ -servername example.com </dev/null 2>/dev/null |
75
+ openssl x509 -noout -ext authorityInfoAccess
76
+ ```
77
+
56
78
  In the output:
57
79
 
58
80
  - A **complete** chain lists two or more certificates under
@@ -60,33 +82,76 @@ In the output:
60
82
  ends with `Verify return code: 0 (ok)`.
61
83
  - A **missing-intermediate** server typically shows **only one** certificate in
62
84
  the chain and a verify error such as
63
- `Verify return code: 21 (unable to verify the first certificate)` — yet the
64
- leaf's AIA block contains a `CA Issuers - URI:` pointer. That combination is the
65
- exact case this fix repairs.
85
+ `Verify return code: 21 (unable to verify the first certificate)`.
86
+ - A `CA Issuers - URI:` line in the second command's output is the pointer
87
+ `AiaTls` follows. One certificate, a verify error and this pointer together
88
+ are a missing intermediate. For playback, the server operator has to send
89
+ the full chain, or the app trusts the intermediate (see
90
+ [Fix playback from the app](#fix-playback-from-the-app)).
91
+
92
+ `AiaTls` can complete it only for connections your app makes itself:
93
+ `HttpURLConnection` through the process default, or an OkHttp client you
94
+ build (see [Advanced](#advanced-custom-okhttp-client)).
66
95
 
67
96
  Prefer a browser? Paste the host into the [SSL Labs server
68
97
  test](https://www.ssllabs.com/ssltest/) — it flags **"Chain issues: Incomplete"**
69
98
  for this exact problem — or use [whatsmychaincert.com](https://whatsmychaincert.com/).
70
99
 
71
100
  > **Want to see a broken chain first?** `incomplete-chain.badssl.com` is a public
72
- > test host that deliberately omits its intermediate — the canonical example of
73
- > this misconfiguration. Run the command above against
74
- > `incomplete-chain.badssl.com:443` to see exactly what the "one certificate +
75
- > verify error + AIA pointer present" signature looks like before you go hunting in
76
- > your own stream.
101
+ > test host that omits its intermediate on purpose. Run both commands above
102
+ > against `incomplete-chain.badssl.com:443` to see the signature: one
103
+ > certificate, a verify error and a `CA Issuers` pointer.
77
104
 
78
- If the chain is complete, or there is no `CA Issuers` AIA pointer, this fix will
105
+ If the chain is complete, or there is no `CA Issuers` AIA pointer, `AiaTls` will
79
106
  **not** help — see [Caveats](#caveats).
80
107
 
108
+ ## Fix playback from the app
109
+
110
+ The player's OkHttp client validates with the platform default trust manager.
111
+ On Android 7 (API 24) and later, that trust manager reads the app's Network
112
+ Security Config. So a `<domain-config>` for the stream's host can trust the
113
+ missing intermediate, with no change to the library.
114
+
115
+ 1. Download the intermediate from the leaf's `CA Issuers - URI` and save it as
116
+ `res/raw/stream_intermediate.crt` (PEM or DER).
117
+ 2. Add `res/xml/network_security_config.xml`:
118
+
119
+ ```xml
120
+ <network-security-config>
121
+ <domain-config>
122
+ <domain includeSubdomains="false">example.com</domain>
123
+ <trust-anchors>
124
+ <certificates src="@raw/stream_intermediate" />
125
+ <certificates src="system" />
126
+ </trust-anchors>
127
+ </domain-config>
128
+ </network-security-config>
129
+ ```
130
+
131
+ 3. Point the `<application>` element of `AndroidManifest.xml` at it with
132
+ `android:networkSecurityConfig="@xml/network_security_config"`.
133
+
134
+ The cost is upkeep. The app now bundles that certificate. When the CA rotates
135
+ its intermediate or the server changes CA, playback fails again until you ship
136
+ an update. Fixing the server's chain has no such cost.
137
+
81
138
  ## Opt in
82
139
 
83
140
  The library ships an **additive** AIA-chasing `SSLSocketFactory` but does **not**
84
- install it for you — installing it sets process-global TLS state, which is a
85
- decision for the host application to make, not a library. Enable it by setting it
86
- as the default in your **existing** `MainApplication`'s `onCreate`, before any
87
- playback begins. `MainApplication.onCreate` runs before React Native loads and
88
- executes your JS bundle, so it is always early enough — no playback can have
89
- started yet.
141
+ install it for you. Installing it changes process-global TLS state, so that is
142
+ the app's decision, not the library's.
143
+
144
+ ::: warning This does not fix playback
145
+ The install below covers your app's own `HttpURLConnection` traffic only, not
146
+ the player (see [The problem](#the-problem)).
147
+
148
+ For a stream that fails in the player, fix the server's chain, or trust the intermediate in a Network Security Config (see
149
+ [Fix playback from the app](#fix-playback-from-the-app)).
150
+ :::
151
+
152
+ To enable it, set it as the default in the `onCreate` of your **existing**
153
+ `MainApplication`. `MainApplication.onCreate` runs before React Native loads your
154
+ JS bundle, so no connection can have started yet.
90
155
 
91
156
  > Add the highlighted line to the `MainApplication` you already have (it lives at
92
157
  > `android/app/src/main/java/.../MainApplication.kt` or `.java`). **Don't create a
@@ -110,7 +175,7 @@ class MainApplication : Application() {
110
175
  HttpsURLConnection.setDefaultSSLSocketFactory(aiaFactory) // [!code ++]
111
176
  installedSslFactory = aiaFactory // [!code ++]
112
177
  } catch (e: Exception) {
113
- // Never let TLS setup block startup; playback keeps default behaviour.
178
+ // Never let TLS setup block startup; connections keep default behaviour.
114
179
  Log.w("MainApplication", "Failed to install AIA-chasing TLS", e)
115
180
  }
116
181
 
@@ -143,7 +208,7 @@ public class MainApplication extends Application {
143
208
  HttpsURLConnection.setDefaultSSLSocketFactory(aiaFactory); // [!code ++]
144
209
  installedSslFactory = aiaFactory; // [!code ++]
145
210
  } catch (Exception e) {
146
- // Never let TLS setup block startup; playback keeps default behaviour.
211
+ // Never let TLS setup block startup; connections keep default behaviour.
147
212
  Log.w("MainApplication", "Failed to install AIA-chasing TLS", e);
148
213
  }
149
214
 
@@ -154,7 +219,8 @@ public class MainApplication extends Application {
154
219
 
155
220
  :::
156
221
 
157
- That's all. The player's data source picks up the process default automatically.
222
+ This reaches every `HttpURLConnection` in the process. It does not reach the
223
+ player (see [The problem](#the-problem)).
158
224
  `AiaTls` ships with the `react-native-audio-browser` Android module you already
159
225
  installed — the `com.audiobrowser.tls` import resolves with no extra Gradle
160
226
  dependency.
@@ -174,53 +240,57 @@ dependency.
174
240
 
175
241
  ## The cleartext fetch is handled for you
176
242
 
177
- The completed-chain check happens over HTTPS — only the side fetch of the _missing
178
- intermediate_ uses the leaf's `CA Issuers` URL, which CAs publish over plain
179
- `http://` (mandated by the CA/Browser Forum Baseline Requirements, to avoid a
180
- chicken-and-egg TLS dependency when fetching the very certificate needed to
181
- complete a TLS chain).
243
+ The stream itself stays on HTTPS. Only the fetch of the _missing intermediate_
244
+ uses the leaf's `CA Issuers` URL, and CAs publish that URL over plain `http://`.
245
+ The CA/Browser Forum Baseline Requirements mandate this: a fetch over TLS would
246
+ need the very certificate that is missing.
247
+
248
+ Apps that target Android 9 (API 28) or later **block cleartext HTTP by default**,
249
+ which would break the fetch in release builds. So the library fetches `http`
250
+ intermediates over a **raw socket**, which your app's `usesCleartextTraffic` and
251
+ network security config do not govern.
182
252
 
183
- That's a problem on most modern apps: targeting Android 9+ (API 28) **blocks
184
- cleartext HTTP by default**, which would silently break the fetch on release
185
- builds. So the library doesn't use Android's HTTP stack for it — the `http`
186
- intermediate fetch goes over a **raw socket**, which isn't subject to your app's
187
- `usesCleartextTraffic` / network-security-config policy. **You don't need to enable
188
- cleartext or add a network security config.**
253
+ **You don't need to enable cleartext or add a network security config.**
189
254
 
190
- This stays safe: the fetched certificate is cryptographically verified to be the
191
- genuine issuer and re-validated against the system trust anchors before use, so a
192
- tampered response over plain HTTP can only fail the chain, never weaken it.
255
+ A fetched certificate joins the chain when its subject matches
256
+ the issuer name of the certificate below it. The platform trust manager then
257
+ validates the completed chain, signatures included, against the system trust
258
+ anchors. So a forged or wrong certificate can only fail the handshake, never
259
+ weaken trust.
193
260
 
194
261
  ## Verify it worked
195
262
 
196
263
  A silent success is hard to tell apart from "my problem was something else," so
197
264
  confirm it explicitly:
198
265
 
199
- 1. **Confirm the factory is installed.** The `catch` above only logs on _failure_,
200
- so **no warning at startup means it installed without throwing** — enough for a
201
- simple app. But it is _not_ enough if your app uses other networking libraries:
202
- `setDefaultSSLSocketFactory` is last-write-wins (see [Caveats](#caveats)), so
203
- another library setting its own default afterward silently deactivates the fix
204
- with no warning. The comparison below is the **only reliable check** in that
205
- case. `AiaTls.socketFactory()` returns a stock TLS socket factory configured
206
- with the AIA-chasing trust manager, so its _class name_ looks identical to the
207
- platform default — don't try to recognise it by class. Instead compare the
208
- process default against the reference the opt-in snippet stored in
209
- `installedSslFactory`. Put this **after** the install `try`/`catch` (so it
210
- reflects the real process default, not the value you just set), anywhere that
211
- runs after startup:
266
+ 1. **Confirm the factory is installed.** The `catch` above logs only on
267
+ _failure_, so **no warning at startup means the install did not throw**. In a
268
+ simple app, that is enough.
269
+
270
+ `setDefaultSSLSocketFactory` is last-write-wins (see [Caveats](#caveats)). If
271
+ another networking library sets its own default later, the fix stops working
272
+ with no warning. To catch that, compare the process default with the
273
+ `installedSslFactory` reference that the opt-in snippet stored.
274
+
275
+ Don't compare class names. `AiaTls.socketFactory()` returns a stock TLS socket
276
+ factory with the AIA-chasing trust manager, so its class looks the same as the
277
+ platform default.
278
+
279
+ Run the comparison after your other networking libraries have initialised,
280
+ for example on first playback or in a debug screen. In `onCreate`, next to the
281
+ install, it is always true and proves nothing.
212
282
 
213
283
  ::: code-group
214
284
 
215
285
  ```kotlin [Kotlin]
216
- // place OUTSIDE the install try/catch — this tests the live process default
286
+ // Run after other networking libraries have initialised.
217
287
  val active = HttpsURLConnection.getDefaultSSLSocketFactory() ===
218
288
  MainApplication.installedSslFactory
219
289
  Log.i("MainApplication", "AIA TLS active: $active")
220
290
  ```
221
291
 
222
292
  ```java [Java]
223
- // place OUTSIDE the install try/catch — this tests the live process default
293
+ // Run after other networking libraries have initialised.
224
294
  boolean active = HttpsURLConnection.getDefaultSSLSocketFactory()
225
295
  == MainApplication.installedSslFactory;
226
296
  Log.i("MainApplication", "AIA TLS active: " + active);
@@ -228,23 +298,25 @@ confirm it explicitly:
228
298
 
229
299
  :::
230
300
 
231
- 2. **Confirm playback recovers.** Play the exact stream that previously failed.
232
- It should now start, and the
233
- `SSLHandshakeException: ... Trust anchor for certification path not found`
234
- should no longer appear in `adb logcat`. No real broken stream on hand? Point
235
- the player at a known-broken-chain source such as
236
- `https://incomplete-chain.badssl.com/` to prove the wiring end-to-end before you
237
- rely on it. Keep one of these around as a regression check for future upgrades.
301
+ 2. **Confirm an `HttpURLConnection` request recovers.** Open
302
+ `https://incomplete-chain.badssl.com/` with `HttpsURLConnection` from your
303
+ app. Without the install it fails with
304
+ `SSLHandshakeException: ... Trust anchor for certification path not found`;
305
+ with it, it succeeds. A stream that fails in the player still fails (see
306
+ [The problem](#the-problem)).
238
307
 
239
308
  ### Still failing after install?
240
309
 
241
310
  Work through these in order:
242
311
 
243
- 1. **Is it even a missing-intermediate case?** Re-run the
312
+ 1. **Is the failure in playback?** The install does not reach the player (see
313
+ [The problem](#the-problem)). Fix the server's chain, or see
314
+ [Fix playback from the app](#fix-playback-from-the-app).
315
+ 2. **Is it even a missing-intermediate case?** Re-run the
244
316
  [diagnosis](#is-this-actually-your-problem). If the chain is complete, there's
245
317
  no `CA Issuers` AIA pointer, or the root is genuinely untrusted/expired, this
246
318
  fix can't repair it — that's a different problem.
247
- 2. **Did the AIA fetch fail?** When the chaser tries to fetch the intermediate and
319
+ 3. **Did the AIA fetch fail?** When the chaser tries to fetch the intermediate and
248
320
  can't, the library logs a warning:
249
321
 
250
322
  ```
@@ -256,18 +328,20 @@ Work through these in order:
256
328
  to enable cleartext; the library's fetch already bypasses that policy.)
257
329
 
258
330
  ::: warning The logger starts with the playback service
259
- The library plants its logging trees when its service first starts, so a fetch
260
- that fails **before** any playback has begun logs nothing — even though the
261
- socket factory is process-wide and already in use. If you see no line at all,
262
- start playback once and retry, or plant your own tree at startup.
331
+ The library plants its logging trees when its service first starts. A fetch
332
+ that fails **before** any playback has begun logs nothing, even though the
333
+ socket factory is process-wide and already in use.
334
+
335
+ If you see no line at all, start playback once and retry, or plant your own
336
+ tree at startup.
263
337
  :::
264
338
 
265
- 3. **Reachable from your environment?** The fetch is a plain outbound request to
339
+ 4. **Reachable from your environment?** The fetch is a plain outbound request to
266
340
  the `CA Issuers - URI` during the handshake, so a corporate proxy, VPN,
267
341
  firewall, or a locked-down emulator network can block it. Confirm the URL
268
342
  resolves by fetching it yourself — `curl -I "http://…/issuer.crt"` — from the
269
343
  same network the device is on.
270
- 4. **Custom Network Security Config?** If your app ships a
344
+ 5. **Custom Network Security Config?** If your app ships a
271
345
  `res/xml/network_security_config.xml` with custom trust anchors or pinning,
272
346
  that's an unrelated cause of TLS failures — this fix won't override it.
273
347
 
@@ -282,23 +356,26 @@ nothing extra happens. Only when the default _rejects_ a chain does it:
282
356
  regardless of your cleartext policy; cached for the process lifetime),
283
357
  3. re-validate the completed chain **against the same system trust anchors**.
284
358
 
285
- A fetched certificate is used only if it is genuinely the issuer of the preceding
286
- one. Because the final decision is still the system trust manager's, this can
287
- **only ever add a missing intermediate — it can never weaken trust**. Untrusted,
288
- expired, or self-signed roots still fail exactly as before.
359
+ A fetched certificate joins the chain when its subject matches the issuer name
360
+ of the certificate before it. The system trust manager makes the final decision
361
+ on the completed chain, signatures included. So this can **only ever add a
362
+ missing intermediate — it can never weaken trust**.
363
+
364
+ Untrusted, expired, or self-signed roots still fail exactly as before.
289
365
 
290
366
  ## Caveats
291
367
 
292
368
  - **Scope.** `setDefaultSSLSocketFactory` is process-wide, so it affects every
293
- `HttpURLConnection`-based TLS connection in your app, not only playback. (It
294
- does not affect OkHttp or a `WebView`, which keep their own TLS stacks.) It is
295
- also last-write-wins: if other code sets its own default afterwards, it
369
+ `HttpURLConnection`-based TLS connection in your app. It does not affect OkHttp
370
+ or a `WebView`, which keep their own TLS stacks, so it does not reach the
371
+ player (see [The problem](#the-problem)).
372
+ - **Last write wins.** If other code sets its own default afterwards, it
296
373
  overrides this one.
297
374
  - **First-connection latency on broken servers.** When a server omits its
298
- intermediate, the first connection performs one extra HTTP request for the
299
- intermediate during the TLS handshake. Well-configured servers pay no cost. The
300
- fetched intermediate is cached for the **process lifetime only**, so this
301
- one-time cost recurs once per cold start for each broken server.
375
+ intermediate, the first connection makes one extra HTTP request during the TLS
376
+ handshake. Well-configured servers pay nothing. The fetched intermediate is
377
+ cached for the **process lifetime only**, so the cost recurs once per cold
378
+ start for each broken server.
302
379
  - **Not a cure-all.** It only rescues servers that omit an intermediate _and_
303
380
  publish an AIA "CA Issuers" pointer that resolves to a trusted root. Servers
304
381
  with no AIA extension, an unreachable intermediate, or a genuinely untrusted
@@ -319,11 +396,11 @@ chain is re-validated by the platform's own trust manager against the same
319
396
  system anchors, so anything Android would have rejected is still rejected.
320
397
 
321
398
  What you are accepting is an outbound request driven by a certificate that just
322
- failed validation. Completing a chain means fetching the missing intermediate
323
- from a URL written into that certificate, so a rejected handshake can cause a
324
- cleartext request to a **host, port and path of the server's choosing** —
325
- including a loopback or LAN address — and that request is deliberately not
326
- subject to your app's `NetworkSecurityPolicy` (see
399
+ failed validation. The fetch URL comes from that certificate. So a rejected
400
+ handshake can cause a cleartext request to a **host, port and path of the
401
+ server's choosing**, including a loopback or LAN address.
402
+
403
+ That request is not subject to your app's `NetworkSecurityPolicy` (see
327
404
  [The cleartext fetch is handled for you](#the-cleartext-fetch-is-handled-for-you)).
328
405
 
329
406
  This is inherent to AIA chasing: browsers and Apple's Secure Transport do the
@@ -331,32 +408,32 @@ same thing, which is why the servers in question work everywhere except Android.
331
408
  It is bounded rather than absent:
332
409
 
333
410
  - the fetch happens **only** when the chain does not already reach one of your
334
- trust anchors, so the common non-path failures — an expired leaf, a hostname
335
- mismatch — do not trigger one. (The test is on the issuer name at the top of
336
- the chain, so a chain topping at a root your device does _not_ carry, such as
337
- a server still serving the retired DST Root CA X3 cross-sign, is still chased
338
- even if its real problem is expiry.)
411
+ trust anchors. Common non-path failures, such as an expired leaf or a hostname
412
+ mismatch, do not trigger one.
413
+ - that test is on the issuer name at the top of the chain. A chain that tops out
414
+ at a root your device does _not_ carry is still chased, even if its real
415
+ problem is expiry. An example is a server that serves the retired DST Root CA
416
+ X3 cross-sign.
339
417
  - the URL is rejected unless it is free of control characters, so it cannot
340
418
  inject request lines of its own;
341
- - at most 3 distinct `CA Issuers` URLs per certificate are tried, a response is
342
- capped at 1 MiB, and at most 5 redirects are followed per fetch;
343
- - the whole chase runs under a single 20-second wall-clock budget — every
344
- connect, TLS handshake, read and redirect hop is clipped to the time
345
- remaining, and nothing new starts once it has expired. So the worst case a
346
- hostile certificate can inflict on one failed handshake is roughly those
347
- 20 seconds, plus at most one DNS lookup that was already in flight when the
348
- budget expired (Java offers no timeout for name resolution, so a lookup can
349
- overrun the budget by its own duration — but a new one is never started past
350
- it);
351
- - the cache holds at most 32 entries, and only successful fetches;
352
- - responses are never trusted on their say-so: a fetched certificate is used
353
- only if it is the genuine issuer of the certificate below it, and the
354
- completed chain still has to validate.
419
+ - the number of `CA Issuers` URLs tried per certificate, the size of a response
420
+ and the redirects followed per fetch are each capped;
421
+ - the whole chase runs under one 20-second wall-clock budget
422
+ (`AiaCertChaser.MAX_CHASE_MILLIS`). Every connect,
423
+ TLS handshake, read and redirect hop is clipped to the time remaining, and
424
+ nothing new starts once the budget has expired. So a hostile certificate can
425
+ hold one failed handshake for the length of the budget. One DNS lookup already in
426
+ flight when the budget expires can add its own duration, because Java has no
427
+ timeout for name resolution. No new lookup starts past the budget;
428
+ - the cache is bounded and holds only successful fetches;
429
+ - responses are never trusted on their say-so. A fetched certificate joins the
430
+ chain only if its subject matches the issuer name being chased, and the
431
+ completed chain still has to validate, signatures included.
355
432
 
356
433
  If your threat model does not allow a failed handshake to trigger an outbound
357
- connection at all, don't install this — or install it on a single client
358
- (see [Advanced: custom OkHttp client](#advanced-custom-okhttp-client)) rather
359
- than as the process default.
434
+ connection at all, don't install this. Or install it on a single client of
435
+ your own (see [Advanced: custom OkHttp client](#advanced-custom-okhttp-client))
436
+ rather than as the process default.
360
437
 
361
438
  ## Advanced: custom OkHttp client
362
439
 
@@ -400,10 +477,12 @@ OkHttpClient client = new OkHttpClient.Builder()
400
477
  :::
401
478
 
402
479
  This confines AIA chasing to that one client and leaves the process default
403
- untouched.
480
+ untouched. It does not reach the player (see [The problem](#the-problem)).
404
481
 
405
- > **Lifecycle.** Each call to `AiaTls.socketFactory()` / `AiaTls.trustManager()`
406
- > builds a fresh component with its **own** fetched-intermediate cache, so build
407
- > once and reuse it (don't construct one per request). The components are
408
- > thread-safe — the fetch cache is a synchronized, bounded LRU — so a single
409
- > instance is safe to install as the process default or share across a client.
482
+ > **Lifecycle.** Each call to `AiaTls.socketFactory()` or `AiaTls.trustManager()`
483
+ > builds a new component with its **own** fetched-intermediate cache. Build one
484
+ > and reuse it; don't build one per request.
485
+ >
486
+ > The components are thread-safe: the fetch cache is a synchronized, bounded
487
+ > LRU. One instance is safe to install as the process default or to share
488
+ > across a client.