From 2d21f092d564b3fbfcfbc7e0ad00f437c68184c0 Mon Sep 17 00:00:00 2001
From: Duncan Tourolle <duncan@tourolle.paris>
Date: Sun, 16 Aug 2026 22:59:47 +0200
Subject: [PATCH] fix(android): stop the webview undoing the network security
 config
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

MainActivity set mixedContentMode = MIXED_CONTENT_ALWAYS_ALLOW together with
allowFileAccess/allowContentAccess = true, which is a blanket cleartext opt-in
reached by hand — the exact thing network_security_config.xml exists to prevent
and its own comment warns against. Nothing needed any of the three:

- file:// is never loaded. Cached thumbnails go through convertFileSrc, which
  on Android resolves to http://asset.localhost/... and is answered by wry's
  request interceptor rather than the filesystem; downloaded media goes over the
  loopback HTTP server (DR-137), which exists precisely because the asset/file
  route cannot stream a large file.
- content:// is never loaded. The manifest's FileProvider is for outbound share
  intents, not webview navigation.
- Mixed content never arises. Tauri serves the UI from http://tauri.localhost
  (use_https_scheme defaults false and is not set), and both 127.0.0.1 and
  asset.localhost are loopback/.localhost origins Chromium treats as potentially
  trustworthy. A plain-HTTP remote server would be mixed content, but the network
  security config already rejects it first — so ALWAYS_ALLOW bought nothing.

COMPATIBILITY_MODE rather than NEVER_ALLOW is a deliberate hedge: the platform
default at targetSdk 21+ is NEVER_ALLOW, so this is still one step looser, and it
keeps passive content working if the analysis missed a path. The two files now
cross-reference each other so the pair cannot drift apart again.

Also records why POST_NOTIFICATIONS is declared but never requested. An audit
read the missing runtime request as a threat to the lockscreen controls; it is
not. A foreground-service notification is explicitly NOT exempt, but a
media-session one is, and the platform predicate (Notification.isMediaNotification)
requires MediaStyle AND a non-null session token. Confirmed on device: appops
POST_NOTIFICATION: ignore with the transport notification live. So no permission
prompt is added and startForeground stays ungated — a guard there would trade a
cosmetic problem for the "did not then call Service.startForeground()" kill.
What is added is the guard matching the real precondition: both builders bind the
token once and log an error if it is ever null, since SystemUI's media carousel
is gated on the same predicate and a token-less notification loses the lockscreen
controls entirely, silently.

TRACES: UR-006, UR-071 | DR-198, DR-199
---
 docs/architecture/09-security.md              |   2 +
 docs/requirements.md                          |   6 +-
 scripts/extract-traces.test.ts                |   6 +-
 .../android/src/main/AndroidManifest.xml      |  29 ++++
 .../com/dtourolle/jellytau/MainActivity.kt    |  49 ++++++-
 .../player/JellyTauPlaybackService.kt         | 127 +++++++++++++++++-
 .../main/res/xml/network_security_config.xml  |   7 +-
 7 files changed, 216 insertions(+), 10 deletions(-)

diff --git a/docs/architecture/09-security.md b/docs/architecture/09-security.md
index b54309ca..5faf88d2 100644
--- a/docs/architecture/09-security.md
+++ b/docs/architecture/09-security.md
@@ -50,6 +50,8 @@ pub struct EncryptedFileStorage; // AES-256-GCM fallback
 | Certificate Validation | System CA store (configurable for self-signed) |
 | Token Transmission | Bearer token in `Authorization` header only |
 | Token Refresh | Handled by Jellyfin server (long-lived tokens) |
+| Android cleartext | `res/xml/network_security_config.xml` blocks cleartext everywhere except `127.0.0.1` (the loopback media server, DR-137/DR-138). The manifest's `usesCleartextTraffic` is ignored once the config is present, so the config is the single authority |
+| Android WebView | `mixedContentMode = COMPATIBILITY` with `allowFileAccess`/`allowContentAccess` both `false` (DR-199). These are the second half of the cleartext policy: `ALWAYS_ALLOW` re-opened by hand what the network security config closes. Change the two together |
 
 ## Local Data Protection
 
diff --git a/docs/requirements.md b/docs/requirements.md
index 5a5d498d..65b07605 100644
--- a/docs/requirements.md
+++ b/docs/requirements.md
@@ -352,6 +352,8 @@ Internal architecture, components, and application logic.
 | DR-195 | Play/pause works on the native path, because the frontend stops claiming a webview element is playing when there is none. `html5_playing` is Rust's record of "a webview `<video>` is active and in this state", and `toggle_playback`, `play` and `pause` all route transport to that element whenever it is set. The player route mirrored element state into it **unconditionally** — from `handleReportStart` and, fatally, from `handleReportProgress`, which VideoPlayer calls on a 10-second interval — so on the native path the frontend re-declared every ten seconds that an element was playing when none existed, and every transport intent was emitted into the void. The pause button was dead from the on-screen tap, from the control bar, and from a direct `player_toggle` invocation, while seek and skip kept working because `player_seek_video` decides elsewhere; that asymmetry is the signature. It also explains the flashing, since the control bar and the JRay overlay both key off `isPlaying`, which was being contradicted on every interval tick. DR-193 clearing the flag at load was necessary but insufficient on its own — the interval put it straight back. The mirror now lives in `mirrorElementStateToRust` in VideoPlayer, gated on `useHtml5Element`, which is the only place that knows whether an element renders at all; the route cannot tell the two paths apart, which is precisely how it came to lie. Confirmed on device by ADB: surface tap and control bar each pause (position frozen across repeated samples, transport label flipped) and resume | Playback | UR-005, UR-003 | Done |
 | DR-196 | Returning from background audio brings the picture back on the **native** path, because the return now restarts the renderer that is actually on screen. The two paths resume by different means: the webview `<video>` reloads off its stream URL, watched by an `$effect` that reinitialises HLS and lets `canplay` drive the seek — while ExoPlayer owns no element and nothing watches the URL on its behalf, so its playback is only ever started by an explicit `player_play_item` + adapter load, issued once from `onMount`. `exitBackgroundAudioHandoff` did only the URL assignment, for both paths, so on the native path it restarted nothing: `player_exit_background_audio` had already stopped the handoff's audio player, leaving the backend holding no item at all. The symptom is a black screen with a play overlay pinned at 0:00, a seek bar at zero, and a play button that does nothing — the process alive and the frontend still logging, since nothing crashed; the transition was simply dropped. The branch is decided by `planHandoffReturn` (pure, in `backgroundAudioHandoff.ts`), which also folds in `shouldResumeOnForeground` so a lockscreen pause during the handoff still wins over the snapshot taken on the way out. Subtitle configurations are reused from the ones resolved at mount, since ExoPlayer sideloads them as `MediaItem.SubtitleConfiguration`s and cannot accept one after `prepare()`. Verified on device: handoff to audio at 69:54, return restored video playing at 70:18 | Playback | UR-040, UR-003 | Done |
 | DR-197 | Continue Watching and Next Up stop showing the same episode. Jellyfin's `/Shows/NextUp` defaults `EnableResumable=true`, which returns a partially-watched episode as its own series' next up — precisely the episode `/Items/Resume` already returns — so the Home "Next Episode" row and the TV landing's Next Up row duplicated Continue Watching card for card. `build_next_up_endpoint` sends `EnableResumable=false`, and because servers predating that parameter ignore it, `filterInProgressNextUpItems` also drops any next-up entry whose id appears in the resume list. It is the mirror of DR-089 and lives beside it: same presentation-layer de-duplication over two lists the frontend already holds, no Jellyfin taxonomy involved. The resume filter still reads its frontier from the *unfiltered* Next Up list, so removing in-progress entries cannot resurrect a stale resume card. The division is then exact: Continue Watching offers episodes the viewer has started and not finished, Next Up offers the episode after the ones they finished | Repository | UR-059 | Done |
+| DR-198 | The lockscreen notification is exempt from `POST_NOTIFICATIONS`, because of the **session token**, not because it belongs to a foreground service — and the difference is what the code now records. `POST_NOTIFICATIONS` was declared in the manifest and requested nowhere, so on Android 13+ it sat permanently denied; an audit read that as a threat to UR-006, since the media notification is what carries the lockscreen transport controls. It is not. Android's own wording is that the permission covers "non-exempt (including Foreground Services (FGS)) notifications", with denied users seeing FGS notices "in the Task Manager but [not] in the notification drawer" — so an FGS notification is explicitly *not* exempt — while separately "Notifications related to media sessions are exempt from this behavior change". The platform predicate is `Notification.isMediaNotification()`, which requires `MediaStyle` **and** a non-null `EXTRA_MEDIA_SESSION`, and it is byte-identical across API 33–36. `NotificationManagerService` uses it to decide whether to drop the post, and SystemUI's media carousel (`MediaDataProcessor.onNotificationAdded`) is gated on the *same* predicate — so a token-less notification is not merely absent from the shade, it never reaches the notification listener and the lockscreen/Quick-Settings controls do not exist at all. Confirmed on device (HONOR ROD2-W09, Android 16 / SDK 36): appops `POST_NOTIFICATION: ignore`, `granted=false`, and the service simultaneously `isForeground=true` with `foregroundNoti=Notification(category=transport actions=3 vis=PUBLIC)`. So **no runtime permission request is added** — a prompt the app does not need is a prompt that can be permanently denied for nothing — and no `checkSelfPermission` gate is placed on `startForeground`, which would trade a cosmetic problem for the "did not then call Service.startForeground()" kill. What is added is the guard that matches the real precondition: `mediaSessionCompat?.sessionToken` is a null-safe call, and the exemption hangs entirely on it, so both builders now bind the token once and log an error if it is ever null while the permission is denied — converting a failure that is invisible unless the tester happened to deny the permission (most grant it reflexively) into a logcat line. The manifest declaration is *kept*, unrequested, and documented: media3 does not need it (media3-session declares no permissions and the `MediaSessionService` guide asks only for the two `FOREGROUND_SERVICE` ones), but the exemption covers media and self-managed-call notifications only, so a download-completion notice (UR-011) would be an ordinary notification and silently dropped — keeping the declaration is what makes adding one a one-file change | Android | UR-006 | Done |
+| DR-199 | The webview stops undoing the network security config. `MainActivity.configureWebViewSettings` set `mixedContentMode = MIXED_CONTENT_ALWAYS_ALLOW` together with `allowFileAccess = true` and `allowContentAccess = true`, which is a blanket cleartext opt-in reached by hand — exactly the thing `network_security_config.xml` exists to prevent and its own comment warns against (DR-138). Nothing needed any of the three. `file://` is never loaded: cached thumbnails go through `convertFileSrc`, which on Android resolves to `http://asset.localhost/…` and is answered by wry's request interceptor rather than the filesystem, and downloaded media goes over the loopback HTTP server (DR-137), which exists precisely because the asset/file route cannot stream a large file. `content://` is never loaded either — the manifest's `FileProvider` is for outbound share intents, not webview navigation. And mixed content never arises: Tauri serves the UI from `http://tauri.localhost` (`use_https_scheme` defaults false and is not set in `tauri.conf.json`), while both `127.0.0.1` and `asset.localhost` are loopback/`.localhost` origins that Chromium treats as potentially trustworthy, so they are not mixed content to begin with. A plain-HTTP *remote* Jellyfin server would be, but the network security config already rejects it before any mixed-content check runs — so `ALWAYS_ALLOW` bought nothing and only widened the hole. `COMPATIBILITY_MODE` rather than `NEVER_ALLOW` is a deliberate hedge and not the default — the platform default at targetSdk 21+ *is* `NEVER_ALLOW` — because none of this can be verified anywhere but a device, and compatibility mode keeps passive content (images) working if the analysis missed a path. `allowFileAccess = false` restores the targetSdk-30+ default; `allowContentAccess = false` is a genuine tightening (its default is true) and is the first thing to look at if something that used to render stops. The two files now cross-reference each other so the pair cannot drift apart again | Security | UR-071 | Done (pending device verification) |
 | DR-194 | Stale pixels in the letterbox bars — the rotation "flash of the previous frame", a ghost control bar stranded in the top bar, each new clock digit drawn over the last (`35:42` with the `1` still showing through the `2`), and menus (sleep timer, quality) leaving their imprint behind. One cause for all of it: **nothing painted the bars.** The window surface is opaque (the theme is not translucent), and for an opaque surface HWUI deliberately does not clear the damaged region before replaying a frame — it assumes the view hierarchy covers every pixel. That hierarchy is window background → video `TextureView` → transparent WebView, and `fitSurfaceToScreen` sizes the TextureView to the *letterboxed* video rect, so the bars were the window background's alone to paint. `setTransparent(true)` cleared that background to `TRANSPARENT`, leaving the bars painted by nobody and whatever was last in the framebuffer surviving in them. Fixed by keeping the window background opaque black while compositing; the WebView's own background is what lets the video through, and the TextureView is drawn on top of the window background, so an opaque one cannot hide it. Three earlier fixes aimed at the window's rotation animation and at TextureView frame-retention (two `postOnAnimation` hops, an `onSurfaceTextureUpdated` reveal, then `ROTATION_ANIMATION_JUMPCUT` + `FLAG_FULLSCREEN`) all missed, because the pixels were never the animation's; the alpha-hiding among them made it worse by blanking the one view that reliably paints its own rect. Those are removed, `FLAG_FULLSCREEN` included — it fought edge-to-edge insets for no gain. Verified on device: ghosting reproduced with native video on, then absent after the fix, across playback, the control bar and a rotation round-trip | Android | UR-003, UR-066 | Done |
 | DR-193 | Play/pause reaches the player that is actually rendering. `toggle_playback`, `play` and `pause` all route to the webview element when `is_html5_active()`, which is `html5_playing.is_some()` — a flag written **only** by the element's own state reports and cleared only when it reports "stopped"/"idle" (or on a background-audio handoff). An element that went away without that final report, or webview-rendered music earlier in the same process, therefore left the flag set, and on Android's native video path every transport intent was emitted as a `ControlCommand` at an element that no longer existed: the pause button did nothing, from the on-screen tap and from the control bar alike, while seek and skip kept working because `player_seek_video` decides elsewhere. Whether it happened at all depended on what had played before, which is exactly what made it read as flaky rather than broken. `load_and_play` — the native load path, and the one the HTML5 video path deliberately avoids via `set_current_item` — now clears the flag, because loading into the native backend *is* the statement that native renders this item. Nothing is lost on the webview path: an element re-establishes its own authority the moment it reports again, so this is the existing "element is gone" semantics applied where it can be known directly rather than inferred from a report that may never arrive | Playback | UR-005, UR-003 | Done |
 | DR-192 | Native video presents through a **TextureView**, not a SurfaceView. A SurfaceView renders on its own layer *outside* the app window and punches a transparent region through it; everything drawn above that hole — for us the entire Svelte UI in a transparent WebView — depends on that composition path, and Android's own graphics documentation states that "overlays do not currently work correctly with SurfaceView or TextureView". The consequences were four symptoms of one cause (DR-191): a frozen progress bar, controls that would not fade, rotation losing the transport UI, and overlays that lingered after the DOM removed them. A TextureView is an ordinary view whose frames are drawn as a texture in the window's normal rendering pass, so there is no second layer and no transparent region, and the WebView above composites like it would over any other view — which is why media3 offers `surface_type="texture_view"` and why it is the standard remedy for ExoPlayer overlay problems. The trade is accepted rather than hidden: TextureView costs more power and memory than SurfaceView and adds a frame of latency, but hardware decode through MediaCodec is untouched, so the reason native video exists survives it. `setVideoTextureView` installs ExoPlayer's own `SurfaceTextureListener`, so the old `SurfaceHolder.Callback` wiring is deleted rather than ported — adding a listener of ours would displace it and the video would never appear. PiP needs no change, since a TextureView is a View and the aspect-ratio probe reads its measured bounds | Android | UR-003, UR-004, UR-041 | Done |
@@ -380,7 +382,7 @@ Internal architecture, components, and application logic.
 | UR-003 | IR-003, IR-004, IR-011 | DR-002, DR-004, DR-010, DR-182, DR-183, DR-184, DR-185, DR-186, DR-187, DR-188, DR-190, DR-191, DR-192, DR-193, DR-194, DR-195, DR-196 |
 | UR-004 | IR-003, IR-004, IR-008, IR-011 | DR-002, DR-004, DR-006, DR-129, DR-171, DR-176, DR-177, DR-181, DR-182, DR-183, DR-185, DR-188 |
 | UR-005 | - | DR-001, DR-005, DR-009, DR-178, DR-179, DR-186, DR-193, DR-195 |
-| UR-006 | IR-005, IR-006, IR-007, IR-008 | - |
+| UR-006 | IR-005, IR-006, IR-007, IR-008 | DR-198 |
 | UR-007 | IR-010 | DR-007, DR-008, DR-016 |
 | UR-008 | IR-010 | DR-007, DR-011 |
 | UR-009 | IR-009, IR-010, IR-011 | - |
@@ -444,7 +446,7 @@ Internal architecture, components, and application logic.
 | UR-068 | - | DR-119 |
 | UR-069 | - | DR-113, DR-114, DR-120 |
 | UR-070 | - | DR-121, DR-122 |
-| UR-071 | IR-032 | DR-123, DR-124, DR-125, DR-126, DR-127, DR-128, DR-133, DR-134, DR-135, DR-136, DR-137, DR-138, DR-170, DR-171, DR-180 |
+| UR-071 | IR-032 | DR-123, DR-124, DR-125, DR-126, DR-127, DR-128, DR-133, DR-134, DR-135, DR-136, DR-137, DR-138, DR-170, DR-171, DR-180, DR-199 |
 | UR-072 | - | DR-156 |
 | UR-073 | - | DR-158 |
 | UR-074 | - | DR-162, DR-177, DR-181 |
diff --git a/scripts/extract-traces.test.ts b/scripts/extract-traces.test.ts
index 9f7e283c..25ed7c75 100644
--- a/scripts/extract-traces.test.ts
+++ b/scripts/extract-traces.test.ts
@@ -175,8 +175,10 @@ describe("live requirements.md", () => {
 
     expect(defined.UR).toBe(75);
     expect(defined.IR).toBe(32);
-    expect(defined.DR).toBe(187);
+    // +2 DR: DR-198 (the POST_NOTIFICATIONS media-session exemption) and
+    // DR-199 (the webview mixed-content/file-access hardening).
+    expect(defined.DR).toBe(189);
     expect(defined.JA).toBe(36);
-    expect(defined.total).toBe(330);
+    expect(defined.total).toBe(332);
   });
 });
diff --git a/src-tauri/android/src/main/AndroidManifest.xml b/src-tauri/android/src/main/AndroidManifest.xml
index 6eb892ac..2f617649 100644
--- a/src-tauri/android/src/main/AndroidManifest.xml
+++ b/src-tauri/android/src/main/AndroidManifest.xml
@@ -25,6 +25,35 @@
     <uses-permission android:name="android.permission.WAKE_LOCK" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
+    <!--
+      Declared, and deliberately NEVER requested at runtime. That is not an
+      oversight, and an audit has flagged it once already — please read before
+      "fixing" it in either direction.
+
+      Nothing the app posts today needs it. The only notification it produces is
+      the playback service's, which is a MediaStyle notification carrying a valid
+      MediaSession token, and "Notifications related to media sessions are exempt
+      from this behavior change". Verified on device (HONOR ROD2-W09, Android 16
+      / SDK 36): appops `POST_NOTIFICATION: ignore`, granted=false, and the
+      transport notification simultaneously live with all three actions and
+      working lockscreen controls. So there is no permission dialog, because a
+      prompt the app does not need is a prompt that can be permanently denied for
+      nothing. Media3 does not require the declaration either — media3-session's
+      own manifest declares no permissions, and the MediaSessionService guide
+      asks only for the two FOREGROUND_SERVICE permissions above.
+
+      It stays declared because the exemption is narrow: it is a property of the
+      NOTIFICATION (MediaStyle *and* a non-null session token), not of the
+      foreground service, and it covers media and self-managed-call notifications
+      only. A download-completion notice (UR-011) would be an ordinary
+      notification and would be silently dropped. Adding one means requesting
+      this permission at runtime — AndroidX ActivityResultContracts.
+      RequestPermission from MainActivity, at the point the feature is used — and
+      handling refusal; keeping the declaration is what makes that a one-file
+      change. See JellyTauPlaybackService.warnIfNotificationWillBeDropped.
+
+      TRACES: UR-006 | DR-198
+    -->
     <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
 
     <!-- AndroidTV support -->
diff --git a/src-tauri/android/src/main/java/com/dtourolle/jellytau/MainActivity.kt b/src-tauri/android/src/main/java/com/dtourolle/jellytau/MainActivity.kt
index 4f1563d9..a7af234e 100644
--- a/src-tauri/android/src/main/java/com/dtourolle/jellytau/MainActivity.kt
+++ b/src-tauri/android/src/main/java/com/dtourolle/jellytau/MainActivity.kt
@@ -502,9 +502,52 @@ class MainActivity : TauriActivity() {
 
         javaScriptEnabled = true
         domStorageEnabled = true
-        allowFileAccess = true
-        allowContentAccess = true
-        mixedContentMode = WebSettings.MIXED_CONTENT_ALWAYS_ALLOW
+
+        // The three settings below used to read
+        //   allowFileAccess = true
+        //   allowContentAccess = true
+        //   mixedContentMode = MIXED_CONTENT_ALWAYS_ALLOW
+        // which handed the webview a blanket cleartext opt-in and undid
+        // res/xml/network_security_config.xml, whose whole point is that only
+        // 127.0.0.1 is exempt from the cleartext ban and that this "must not
+        // become a blanket cleartext opt-in" (DR-138). Nothing needed any of it:
+        //
+        // - `file://` is never loaded. Cached thumbnails go through
+        //   `convertFileSrc` (imageCache.ts), which on Android resolves to
+        //   `http://asset.localhost/...` — a Tauri custom protocol answered by
+        //   wry's request interceptor, not the filesystem. Downloaded media goes
+        //   through `media_local_url` → the loopback HTTP server on 127.0.0.1
+        //   (media_server.rs, DR-137), which exists precisely *because* the
+        //   asset/file route cannot stream a large file.
+        // - `content://` is never loaded either. The manifest's FileProvider is
+        //   for outbound share intents, not for webview navigation.
+        // - Mixed content never arises. Tauri serves the UI from
+        //   `http://tauri.localhost` (`use_https_scheme` is false by default and
+        //   is not set in tauri.conf.json), and both the loopback media server
+        //   and `asset.localhost` are loopback/`.localhost` origins, which
+        //   Chromium treats as potentially trustworthy — so they are not mixed
+        //   content in the first place. A plain-HTTP *remote* Jellyfin server
+        //   would be, but the network security config already rejects it before
+        //   the mixed-content check is ever reached, so ALWAYS_ALLOW bought
+        //   nothing and only widened the hole.
+        //
+        // COMPATIBILITY_MODE rather than NEVER_ALLOW is a deliberate hedge, not
+        // the default: the platform default at targetSdk 21+ is NEVER_ALLOW, so
+        // this is still one step looser than "stop overriding". It keeps passive
+        // content (images) working if some path the analysis above missed turns
+        // out to need it, which matters because this change cannot be verified
+        // anywhere but a device. Tighten to NEVER_ALLOW once offline video and
+        // cached artwork are confirmed on real hardware.
+        //
+        // `allowFileAccess = false` is the targetSdk-30+ platform default being
+        // restored; `allowContentAccess = false` is a genuine tightening (its
+        // default is true) and is the one to look at first if anything that used
+        // to render stops.
+        //
+        // TRACES: UR-071 | DR-199
+        allowFileAccess = false
+        allowContentAccess = false
+        mixedContentMode = WebSettings.MIXED_CONTENT_COMPATIBILITY_MODE
 
         android.util.Log.d("MainActivity", "WebView fully configured for media playback")
       }
diff --git a/src-tauri/android/src/main/java/com/dtourolle/jellytau/player/JellyTauPlaybackService.kt b/src-tauri/android/src/main/java/com/dtourolle/jellytau/player/JellyTauPlaybackService.kt
index b7391f34..c1be0e53 100644
--- a/src-tauri/android/src/main/java/com/dtourolle/jellytau/player/JellyTauPlaybackService.kt
+++ b/src-tauri/android/src/main/java/com/dtourolle/jellytau/player/JellyTauPlaybackService.kt
@@ -245,9 +245,103 @@ class JellyTauPlaybackService : MediaSessionService() {
         }
     }
 
+    /**
+     * Whether this process could post an *ordinary* notification and have the
+     * user see it.
+     *
+     * Deliberately **not** a gate on anything this service posts today — see
+     * [warnIfNotificationWillBeDropped]. `POST_NOTIFICATIONS` is declared in the
+     * manifest but never requested, so on Android 13+ this is normally `false`,
+     * and that is the intended state. It is read only to decide whether a
+     * token-less notification would be dropped.
+     */
+    private fun hasPostNotificationsPermission(): Boolean =
+        Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU ||
+            checkSelfPermission(android.Manifest.permission.POST_NOTIFICATIONS) ==
+                android.content.pm.PackageManager.PERMISSION_GRANTED
+
+    /**
+     * The media-session token is what makes this service's notifications legal
+     * without `POST_NOTIFICATIONS` — do not drop it.
+     *
+     * Android 13 (API 33) gates notifications behind the `POST_NOTIFICATIONS`
+     * runtime permission, and a foreground-service notification is explicitly
+     * **not** exempt: "Android 13 (API level 33) and higher supports a runtime
+     * permission for sending non-exempt (including Foreground Services (FGS))
+     * notifications from an app: POST_NOTIFICATIONS", and with it denied the
+     * user "still see[s] notices related to foreground services in the Task
+     * Manager but [doesn't] see them in the notification drawer".
+     *
+     * A *media-session* notification is exempt, however: "Notifications related
+     * to media sessions are exempt from this behavior change." That exemption is
+     * a property of the notification, not of the service — the platform decides
+     * it from the posted `Notification` itself, which must carry `MediaStyle`
+     * **and** a valid `MediaSession` token. Every notification this service
+     * builds does (`MediaStyle().setMediaSession(mediaSessionCompat.sessionToken)`,
+     * with `mediaSessionCompat` created in `onCreate`, i.e. before any post), so
+     * the shade entry and the lockscreen transport controls behind UR-006 appear
+     * whether or not the permission was ever granted. That is why this app asks
+     * for nothing at runtime and shows the user no permission dialog.
+     *
+     * The trap it leaves is a silent one, and it is worse than a missing shade
+     * entry — which is what this exists to make loud. The platform predicate is
+     * `Notification.isMediaNotification()`, requiring MediaStyle **and** a
+     * non-null `EXTRA_MEDIA_SESSION`; `NotificationManagerService` uses it to
+     * decide whether to drop the post, and SystemUI's media carousel
+     * (`MediaDataProcessor.onNotificationAdded`) is gated on *the same*
+     * predicate. So a token-less notification is blocked before it reaches the
+     * notification listener, and the lockscreen/Quick Settings transport
+     * controls — the whole of UR-006 — never appear at all, with no error and no
+     * log anywhere. `mediaSessionCompat?.sessionToken` is a null-safe call, so
+     * that failure is one stray initialisation-order change away.
+     *
+     * The exemption also covers only media and self-managed-call notifications,
+     * so a genuinely non-media notification — a download-completion notice
+     * (UR-011), say — gets none of it. Adding one means requesting
+     * `POST_NOTIFICATIONS` at runtime first (AndroidX
+     * `ActivityResultContracts.RequestPermission`, launched from `MainActivity`
+     * at the point the feature is used, handling refusal), not merely calling
+     * `notify`; the manifest keeps the declaration so that stays a one-file
+     * change. Verified unchanged across API 33–36.
+     *
+     * TRACES: UR-006 | DR-198
+     */
+    private fun warnIfNotificationWillBeDropped(token: MediaSessionCompat.Token?) {
+        if (token != null) return
+        if (hasPostNotificationsPermission()) return
+        android.util.Log.e(
+            "JellyTauPlaybackService",
+            "Posting a notification with NO MediaSession token while POST_NOTIFICATIONS " +
+                "is denied: it is not exempt and Android will drop it silently. " +
+                "Lockscreen/shade transport controls (UR-006) will be missing."
+        )
+    }
+
     override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
         // Start as foreground service immediately to avoid crash
         // Media3 will replace this with its own notification
+        //
+        // startForeground() is deliberately NOT gated on POST_NOTIFICATIONS, and
+        // an audit asking for such a guard has been answered once already — do
+        // not re-raise it. Two independent reasons:
+        //
+        // 1. The notification does not need the permission. It is exempt because
+        //    it is a media-session notification (see
+        //    warnIfNotificationWillBeDropped). Device evidence, HONOR ROD2-W09 on
+        //    Android 16 / SDK 36: appops reports `POST_NOTIFICATION: ignore` and
+        //    `granted=false`, while the same dumpsys shows this service
+        //    isForeground=true with `foregroundNoti=Notification(category=
+        //    transport actions=3 vis=PUBLIC)` live and the lockscreen transport
+        //    controls working.
+        // 2. Skipping this call after startForegroundService() is a hard contract
+        //    violation — the system kills the process with "did not then call
+        //    Service.startForeground()". So a guard here would convert a cosmetic
+        //    problem into a crash.
+        //
+        // A denied permission must degrade to a missing *notification*, never to
+        // a missing startForeground.
+        //
+        // TRACES: UR-006 | DR-198
         val notification = createBasicNotification()
         startForeground(NOTIFICATION_ID, notification)
         return super.onStartCommand(intent, flags, startId)
@@ -263,6 +357,11 @@ class JellyTauPlaybackService : MediaSessionService() {
             PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT
         )
 
+        // onCreate builds mediaSessionCompat, and onStartCommand cannot run
+        // before onCreate, so this is expected to be non-null here.
+        val sessionToken = mediaSessionCompat?.sessionToken
+        warnIfNotificationWillBeDropped(sessionToken)
+
         return NotificationCompat.Builder(this, NOTIFICATION_CHANNEL_ID)
             .setContentTitle("JellyTau")
             .setContentText("Playing")
@@ -270,7 +369,7 @@ class JellyTauPlaybackService : MediaSessionService() {
             .setContentIntent(pendingIntent)
             .setStyle(
                 androidx.media.app.NotificationCompat.MediaStyle()
-                    .setMediaSession(mediaSessionCompat?.sessionToken)
+                    .setMediaSession(sessionToken)
                     .setShowActionsInCompactView(0, 1, 2) // Show all 3 buttons in compact view
             )
             .addAction(
@@ -446,6 +545,24 @@ class JellyTauPlaybackService : MediaSessionService() {
     /**
      * Update the notification with current media metadata and playback state.
      * This should be called whenever metadata or playback state changes.
+     *
+     * This `notify()` reuses [NOTIFICATION_ID], so while the service is
+     * foreground it updates the foreground notification in place. It is **not**
+     * guarded on the service being foreground, and does not need to be, because
+     * the exemption that keeps it postable is a property of the notification
+     * (MediaStyle + session token) rather than of the foreground state — see
+     * [warnIfNotificationWillBeDropped].
+     *
+     * That distinction is load-bearing, because this *is* reachable with the
+     * service alive but not foreground. Every caller arrives over JNI from Rust
+     * on a non-main thread against [getInstance], which is non-null from
+     * `onCreate` to `onDestroy`: it can therefore interleave between `onCreate`
+     * and `onStartCommand`, and a media3 `MediaSessionService` is also created
+     * by a plain *bind* from a MediaController with no `startForeground` at all.
+     * Were the exemption a foreground-service one, those windows would silently
+     * drop the update; being a media-session one, they do not.
+     *
+     * TRACES: UR-006 | DR-198
      */
     private fun updateNotification(title: String, artist: String, isPlaying: Boolean) {
         val intent = packageManager.getLaunchIntentForPackage(packageName)
@@ -456,6 +573,12 @@ class JellyTauPlaybackService : MediaSessionService() {
             PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT
         )
 
+        // The token is what exempts this from POST_NOTIFICATIONS; losing it here
+        // would make every metadata update vanish from the shade and lockscreen
+        // while the service kept running. See warnIfNotificationWillBeDropped.
+        val sessionToken = mediaSessionCompat?.sessionToken
+        warnIfNotificationWillBeDropped(sessionToken)
+
         val notification = NotificationCompat.Builder(this, NOTIFICATION_CHANNEL_ID)
             .setContentTitle(title)
             .setContentText(artist)
@@ -463,7 +586,7 @@ class JellyTauPlaybackService : MediaSessionService() {
             .setContentIntent(pendingIntent)
             .setStyle(
                 androidx.media.app.NotificationCompat.MediaStyle()
-                    .setMediaSession(mediaSessionCompat?.sessionToken)
+                    .setMediaSession(sessionToken)
                     .setShowActionsInCompactView(0, 1, 2) // Show all 3 buttons in compact view
             )
             .addAction(
diff --git a/src-tauri/android/src/main/res/xml/network_security_config.xml b/src-tauri/android/src/main/res/xml/network_security_config.xml
index 26a4daf5..80452413 100644
--- a/src-tauri/android/src/main/res/xml/network_security_config.xml
+++ b/src-tauri/android/src/main/res/xml/network_security_config.xml
@@ -12,7 +12,12 @@
   remote server still has to be HTTPS — this must not become a blanket
   cleartext opt-in.
 
-  TRACES: UR-071 | DR-138
+  This file is only half the policy. MainActivity.configureWebViewSettings sets
+  the webview's mixedContentMode and its file/content access flags; setting
+  MIXED_CONTENT_ALWAYS_ALLOW there re-opened by hand what this config closes,
+  which is DR-199. Change the two together, or not at all.
+
+  TRACES: UR-071 | DR-138, DR-199
 -->
 <network-security-config>
     <base-config cleartextTrafficPermitted="false" />