Merge branch 'pr/fix/provider-session-identity(84f5e112)' into work/post190-source-acceptance

Reuse only unexpired JWTs for the verified selected native public key. Invalidate stale session credentials and in-flight responses on account switching or logout, notify app state before authentication, and accept identity bootstrap only from the expected signer origin.

Preserve saved profiles and private keys. Validation: 23 focused provider tests passed, including cached-key mismatch, expiry, late response, logout and repeated-selection regressions.

.dockerignore

@@ -4,7 +4,13 @@
 # Allow neode-ui (frontend + mock backend + docker configs)
 !neode-ui/
 
-# Allow demo assets (AIUI pre-built dist)
+!aiui/
+aiui/**/node_modules
+aiui/**/dist
+aiui/**/.turbo
+aiui/**/.build-aiui-last-*
+
+# Allow curated demo assets
 !demo/
 
 # Allow the Bitcoin UI + ElectrumX UI mock shells (served from /docker/*)

.gitea/workflows/demo-images.yml

@@ -17,6 +17,9 @@ on:
     branches: [main]
     paths:
       - 'neode-ui/**'
+      - 'aiui/**'
+      - 'scripts/build-aiui.sh'
+      - '.dockerignore'
       - 'docker-compose.demo.yml'
       - '.gitea/workflows/demo-images.yml'
   workflow_dispatch:
@@ -65,10 +68,12 @@ jobs:
           push: true
           build-args: |
             VITE_DEMO=1
+            SOURCE_REVISION=${{ github.sha }}
           tags: |
             ${{ vars.DEMO_REGISTRY }}/archy-demo-web:demo
             ${{ vars.DEMO_REGISTRY }}/archy-demo-web:${{ github.sha }}
 
       - name: Trigger Portainer redeploy
-        if: ${{ success() && secrets.PORTAINER_WEBHOOK != '' }}
+        # Source pushes prepare images; public deployment is an explicit post-release action.
+        if: ${{ success() && github.event_name == 'workflow_dispatch' && secrets.PORTAINER_WEBHOOK != '' }}
         run: curl -fsS -X POST "${{ secrets.PORTAINER_WEBHOOK }}"

.github/workflows/demo-images.yml

@@ -17,6 +17,9 @@ on:
     branches: [main]
     paths:
       - 'neode-ui/**'
+      - 'aiui/**'
+      - 'scripts/build-aiui.sh'
+      - '.dockerignore'
       - 'docker-compose.demo.yml'
       - '.github/workflows/demo-images.yml'
   workflow_dispatch:
@@ -65,10 +68,12 @@ jobs:
           push: true
           build-args: |
             VITE_DEMO=1
+            SOURCE_REVISION=${{ github.sha }}
           tags: |
             ${{ vars.DEMO_REGISTRY }}/archy-demo-web:demo
             ${{ vars.DEMO_REGISTRY }}/archy-demo-web:${{ github.sha }}
 
       - name: Trigger Portainer redeploy
-        if: ${{ success() && secrets.PORTAINER_WEBHOOK != '' }}
+        # Source pushes prepare images; public deployment is an explicit post-release action.
+        if: ${{ success() && github.event_name == 'workflow_dispatch' && secrets.PORTAINER_WEBHOOK != '' }}
         run: curl -fsS -X POST "${{ secrets.PORTAINER_WEBHOOK }}"

AGENTS.md

@@ -0,0 +1,73 @@
+# Blocking incident: Framework LND startup and false zero balance
+
+Before starting or resuming work in this repository, read
+`docs/incident-framework-lnd-startup.md` and check its status.
+
+The user explicitly required this incident to take priority over later work.
+While its status is OPEN:
+
+- Surface this blocker at session start, including when the user asks for unrelated work.
+- Prioritize investigation and repair on the actual Framework node. If access is
+  unavailable, ask for it and continue useful offline investigation; defer unrelated
+  work unless the user explicitly overrides this priority.
+- A manual LND restart, a source patch, passing local tests, or publishing an OTA
+  does not resolve the incident. Do not mark it fixed until the Framework's startup,
+  Receive flow, and balance behavior are verified on the node, including a controlled
+  reboot with access and recovery arrangements in place.
+- Preserve wallet identity, wallet/channel databases, credentials, and backups.
+  Never run wallet wipe/recreation as an automatic investigation or recovery step.
+- Record evidence, changes, validation, and remaining work in the incident document.
+
+This priority comes from the user's explicit instruction on 2026-09-15. It remains
+in effect across sessions until the documented acceptance criteria are met or the
+user explicitly changes it.
+
+## Unit tests on a live node
+
+Run backend unit tests through `scripts/test-backend-isolated.sh`. Do not run
+unrestricted `cargo test` on a node with installed apps: older mocked-runtime
+tests still reached real service commands. The runner isolates wallet data,
+service buses, container storage, networking, and process IDs. Compilation with
+`cargo test --no-run` is safe. Keep separately authorized live checks explicit.
+
+## Active release regression checklist
+
+Before resuming release work, read
+`docs/post-1.8.22-regressions-20261001.md` and retain its unfinished tasks.
+The operator requested that every reported issue be tracked, fixed and tested
+before another OTA/ISO. Keep source/unit-test results separate from actual-node
+acceptance. In particular, paid-file recovery must not send another payment,
+and app cleanup must preserve wallets, persistent data and uninstall decisions.
+Do not mark the new paid-file incident resolved merely because the earlier
+Framework LND startup incident was closed.
+
+## Gitea and ngit mirror parity
+
+Nostr Git (`ngit`) is the canonical contribution and review platform. Gitea
+(`origin`) mirrors accepted code on `main` and release tags. Both are required
+publication mirrors; duplicate PRs and proposal branches on Gitea are not required.
+For every change, including fixes and release preparation:
+
+- Review and merge once. Push the exact same resulting commits to both mirrors;
+  never independently squash, rebase or merge the same change on each platform.
+- Open new contributions and PRs on ngit; review and merge there, then mirror the
+  exact accepted main commits to Gitea. Record the ngit proposal and resulting
+  merge commit in the release ledger. Existing Gitea PRs must be reviewed and
+  explicitly linked to their ngit replacement or accepted result before closing;
+  do not abandon contributions or mark unmerged changes as merged. PR numbers,
+  reviews and discussions remain platform-specific; matching Git refs does not
+  prove their synchronization.
+- Push main and release tags to both mirrors. Preserve commit history
+  and annotated tag objects/signatures. Do not resolve drift by force pushing,
+  deleting remote refs, or rewriting published history without explicit approval.
+- After publishing source, run `python3 scripts/check-git-mirrors.py --local`.
+  Include each additional shared branch or release tag with repeated `--ref`
+  arguments (full `refs/heads/...` or `refs/tags/...` names).
+- Before OTA, catalog or ISO publication, require matching reviewed local and
+  remote main and release tag refs, and record ngit PR dispositions in the
+  release acceptance ledger. A failed push, unavailable mirror, missing ref or
+  mismatch blocks publication; never describe a partial push as synchronized.
+  Run `--all` for a complete advertised branch/tag audit; a main-only pass must
+  never be described as full historical mirror parity. Proposal-only branches
+  may intentionally differ. Existing unrelated drift
+  must be inventoried explicitly rather than silently overwritten.

Android/app/build.gradle.kts

@@ -11,8 +11,8 @@ android {
         applicationId = "com.archipelago.app"
         minSdk = 26
         targetSdk = 35
-        versionCode = 52
-        versionName = "0.5.32"
+        versionCode = 57
+        versionName = "0.5.37"
 
         vectorDrawables {
             useSupportLibrary = true
@@ -142,6 +142,9 @@ tasks.matching {
 }.configureEach { dependsOn("buildRustArm64") }
 
 dependencies {
+    testImplementation("junit:junit:4.13.2")
+    testImplementation("com.squareup.okhttp3:mockwebserver:4.12.0")
+    testImplementation("org.robolectric:robolectric:4.14.1")
     val composeBom = platform("androidx.compose:compose-bom:2024.05.00")
     implementation(composeBom)
 

Android/app/src/main/AndroidManifest.xml

@@ -10,6 +10,7 @@
     <!-- Embedded FIPS mesh tunnel (ArchyVpnService) runs as a foreground service. -->
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
     <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
 
     <application
@@ -37,11 +38,13 @@
 
         <activity
             android:name=".MainActivity"
+            android:supportsPictureInPicture="true"
             android:exported="true"
             android:launchMode="singleTask"
+            android:resizeableActivity="true"
             android:theme="@style/Theme.Archipelago.Splash"
             android:windowSoftInputMode="adjustResize"
-            android:configChanges="orientation|screenSize|screenLayout|keyboardHidden">
+            android:configChanges="orientation|screenSize|screenLayout|smallestScreenSize|keyboardHidden">
             <intent-filter>
                 <action android:name="android.intent.action.MAIN" />
                 <category android:name="android.intent.category.LAUNCHER" />
@@ -65,6 +68,12 @@
             </intent-filter>
         </activity>
 
+        <service
+            android:name=".ui.screens.CompanionAudioService"
+            android:exported="false"
+            android:stopWithTask="false"
+            android:foregroundServiceType="mediaPlayback" />
+
         <!-- Embedded FIPS mesh node: split-tunnel VpnService (fd00::/8 only),
              configured entirely by scanning the node's pairing QR. -->
         <service

Android/app/src/main/java/com/archipelago/app/MainActivity.kt

@@ -9,11 +9,18 @@ import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
 import androidx.core.splashscreen.SplashScreen.Companion.installSplashScreen
 import com.archipelago.app.ui.navigation.AppNavHost
-import com.archipelago.app.ui.screens.releaseKioskWebView
+import com.archipelago.app.ui.screens.finishKioskActivity
 import com.archipelago.app.ui.theme.ArchipelagoTheme
 import kotlinx.coroutines.flow.MutableStateFlow
 
 class MainActivity : ComponentActivity() {
+    internal var cloudVideoPip: com.archipelago.app.ui.screens.CloudVideoPip? = null
+    override fun onPictureInPictureModeChanged(active: Boolean, config: android.content.res.Configuration) {
+        super.onPictureInPictureModeChanged(active, config)
+        cloudVideoPip?.modeChanged(active)
+    }
+    override fun onStop() { cloudVideoPip?.stopped(); super.onStop() }
+
 
     // Pairing deep link (archipelago://pair?...) from the launch intent or a
     // later one (launchMode=singleTask). Consumed by AppNavHost.
@@ -49,11 +56,8 @@ class MainActivity : ComponentActivity() {
 
     override fun onDestroy() {
         super.onDestroy()
-        // Swiped out of recents (or otherwise finished) — let go of the
-        // retained kiosk WebView so the next launch starts clean. Without
-        // this the FIPS service keeps the process (and the static WebView)
-        // alive, and "close the app" no longer restarted it. isFinishing
-        // keeps config changes (rotation) on the fast reattach path.
-        if (isFinishing) releaseKioskWebView()
+        // Keep an authorized playing WebView owned by the media service;
+        // discard ordinary dashboard state when the task is finished.
+        if (isFinishing) finishKioskActivity()
     }
 }

Android/app/src/main/java/com/archipelago/app/ui/components/NESMenu.kt

@@ -74,6 +74,7 @@ import androidx.compose.ui.unit.sp
 import com.archipelago.app.R
 import com.archipelago.app.data.ServerEntry
 import com.archipelago.app.ui.screens.restartCompanionApp
+import com.archipelago.app.ui.screens.CompanionAudioDiagnostics
 import com.archipelago.app.ui.theme.BitcoinOrange
 import com.archipelago.app.ui.theme.SurfaceDark
 import com.archipelago.app.ui.theme.TextMuted
@@ -252,6 +253,7 @@ private fun MenuPanel(
                             HubPage.FIPS -> "FIPS Mesh"
                             HubPage.BACKUP -> "Backup & Restore"
                             HubPage.SIGNER -> "Remote Signer"
+                            HubPage.AUDIO -> "Playback diagnostics"
                             HubPage.HUB -> "Menu"
                         },
                         color = TextPrimary, fontSize = 20.sp, fontWeight = FontWeight.SemiBold, letterSpacing = 1.sp,
@@ -307,6 +309,7 @@ private fun MenuPanel(
                     onDismiss()
                     restartCompanionApp(hubContext)
                 }
+                HubCard(Icons.Default.Dashboard, "Playback diagnostics", "Local background audio status") { page = HubPage.AUDIO }
                 val versionLabel = remember {
                     runCatching {
                         hubContext.packageManager
@@ -451,6 +454,17 @@ private fun MenuPanel(
                 }
             }
 
+            HubPage.AUDIO -> {
+                val context = LocalContext.current
+                val clipboard = LocalClipboardManager.current
+                var report by remember { mutableStateOf(CompanionAudioDiagnostics.report(context)) }
+                var copied by remember { mutableStateOf(false) }
+                Text("Local status only. No track names, addresses, credentials, or automatic uploads.", color = TextMuted, fontSize = 12.sp)
+                Text(report, color = TextPrimary, fontSize = 12.sp)
+                MenuItem(label = "Refresh", onClick = { report = CompanionAudioDiagnostics.report(context); copied = false })
+                MenuItem(label = if (copied) "Copied" else "Copy report", onClick = { clipboard.setText(AnnotatedString(report)); copied = true })
+            }
+
             HubPage.FIPS -> {
                 FipsSection(embedded = true)
             }
@@ -470,7 +484,7 @@ private fun MenuPanel(
     }
 }
 
-private enum class HubPage { HUB, NODES, FIPS, BACKUP, SIGNER }
+private enum class HubPage { HUB, NODES, FIPS, BACKUP, SIGNER, AUDIO }
 
 /** Big tappable destination card for the hub page: icon + title + subtitle. */
 @Composable

Android/app/src/main/java/com/archipelago/app/ui/screens/CloudVideoPip.kt

@@ -0,0 +1,194 @@
+package com.archipelago.app.ui.screens
+
+import android.app.PendingIntent
+import android.app.PictureInPictureParams
+import android.app.RemoteAction
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.ContextWrapper
+import android.content.Intent
+import android.content.IntentFilter
+import android.content.pm.PackageManager
+import android.graphics.Rect
+import android.graphics.drawable.Icon
+import android.net.Uri
+import android.util.Rational
+import android.webkit.WebView
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.remember
+import androidx.compose.ui.platform.LocalContext
+import androidx.core.content.ContextCompat
+import androidx.webkit.JavaScriptReplyProxy
+import androidx.webkit.WebMessageCompat
+import androidx.webkit.WebViewCompat
+import androidx.webkit.WebViewFeature
+import com.archipelago.app.MainActivity
+import org.json.JSONObject
+import java.net.URI
+import java.util.UUID
+
+internal fun cloudVideoOrigin(value: String?): String? = runCatching {
+    val uri = URI(value ?: return null)
+    val scheme = uri.scheme?.lowercase() ?: return null
+    if (scheme !in setOf("http", "https") || uri.userInfo != null) return null
+    val host = uri.host?.lowercase() ?: return null
+    val port = uri.port.takeUnless { it == -1 || it == if (scheme == "https") 443 else 80 }
+    "$scheme://$host${port?.let { ":$it" } ?: ""}"
+}.getOrNull()
+
+internal fun cloudVideoSenderAllowed(currentUrl: String?, source: String, allowed: Set<String>, mainFrame: Boolean): Boolean {
+    val origin = cloudVideoOrigin(source)
+    return mainFrame && origin != null && origin in allowed && cloudVideoOrigin(currentUrl) == origin
+}
+
+/** Only the dashboard's origin-restricted main-frame channel can arm Cloud PiP.
+ * No URL, cookies, bearer token or second media player enters native storage. */
+internal class CloudVideoPip(private val activity: MainActivity?, private val fullscreen: WebViewFullscreen) {
+    private class Binding(val origins: Set<String>, var owner: java.lang.ref.WeakReference<CloudVideoPip>)
+    companion object {
+        private val bindings = java.util.WeakHashMap<WebView, Binding>()
+    }
+    private var webView: WebView? = null
+    private var session: String? = null
+    private var reply: JavaScriptReplyProxy? = null
+    private var playing = false
+    private var ratio = Rational(16, 9)
+    private var entered = false
+    private var registered = false
+    private val action = "com.archipelago.app.CLOUD_VIDEO_PIP.${UUID.randomUUID()}"
+    private val receiver = object : BroadcastReceiver() {
+        override fun onReceive(context: Context?, intent: Intent?) {
+            if (!entered || intent?.action != action || intent.getStringExtra("session") != session) return
+            event("command", if (playing) "pause" else "play")
+        }
+    }
+    private fun supported() = activity?.packageManager?.hasSystemFeature(PackageManager.FEATURE_PICTURE_IN_PICTURE) == true
+    private fun event(state: String, command: String? = null) {
+        val message = JSONObject().put("type", "event").put("session", session).put("state", state)
+        if (command != null) message.put("command", command)
+        runCatching { reply?.postMessage(message.toString()) }
+    }
+    private fun params(): PictureInPictureParams {
+        val owner = requireNotNull(activity)
+        val intent = Intent(action).setPackage(owner.packageName).putExtra("session", session)
+        val pending = PendingIntent.getBroadcast(owner, 0, intent, PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE)
+        val control = RemoteAction(Icon.createWithResource(owner, if (playing) android.R.drawable.ic_media_pause else android.R.drawable.ic_media_play),
+            if (playing) "Pause" else "Play", if (playing) "Pause video" else "Play video", pending)
+        val bounds = Rect()
+        val builder = PictureInPictureParams.Builder().setAspectRatio(ratio).setActions(listOf(control))
+        if (fullscreen.bounds(bounds)) builder.setSourceRectHint(bounds)
+        return builder.build()
+    }
+    fun attach(view: WebView, allowedUrls: List<String>) {
+        if (!WebViewFeature.isFeatureSupported(WebViewFeature.WEB_MESSAGE_LISTENER)) return
+        val origins = allowedUrls.mapNotNull(::cloudVideoOrigin).toSet()
+        if (origins.isEmpty()) return
+        webView = view
+        val existing = bindings[view]
+        if (existing != null) {
+            // Rebind the retained document; removing/re-adding a listener would
+            // require a reload and strand the page's existing JS bridge.
+            if (existing.origins != origins) {
+                existing.owner.clear(); webView = null
+                return // The page receives a bounded unavailable response; reconnect reloads policy.
+            }
+            existing.owner = java.lang.ref.WeakReference(this)
+            return
+        }
+        val binding = Binding(origins, java.lang.ref.WeakReference(this))
+        bindings[view] = binding
+        WebViewCompat.addWebMessageListener(view, "ArchipelagoCloudVideo", origins,
+            object : WebViewCompat.WebMessageListener {
+                override fun onPostMessage(web: WebView, message: WebMessageCompat, sourceOrigin: Uri, isMainFrame: Boolean, proxy: JavaScriptReplyProxy) {
+                    binding.owner.get()?.receive(web, message, sourceOrigin, isMainFrame, proxy, binding.origins)
+                }
+            })
+    }
+    private fun receive(web: WebView, message: WebMessageCompat, sourceOrigin: Uri, isMainFrame: Boolean, proxy: JavaScriptReplyProxy, origins: Set<String>) {
+        if (web !== webView || !cloudVideoSenderAllowed(web.url, sourceOrigin.toString(), origins, isMainFrame)) return
+        val raw = runCatching { message.data }.getOrNull() ?: return
+        if (raw.length > 2048) return
+        val request = runCatching { JSONObject(raw) }.getOrNull() ?: return
+        val id = request.optString("id")
+        if (!id.matches(Regex("[0-9a-f-]{36}"))) return
+        val response = JSONObject().put("id", id)
+        runCatching {
+            when (request.optString("action")) {
+                "capabilities" -> response.put("supported", supported()).put("version", 1)
+                "arm" -> {
+                    check(supported()) { "Picture-in-picture is unavailable on this device." }
+                    check(!entered) { "A video is already in picture-in-picture." }
+                    val width = request.optInt("width", 0); val height = request.optInt("height", 0)
+                    check(width in 1..16384 && height in 1..16384) { "Video dimensions are not ready." }
+                    ratio = Rational(((width.toDouble() / height).coerceIn(1.0 / 2.39, 2.39) * 10000).toInt(), 10000)
+                    session = id; reply = proxy; playing = request.optBoolean("playing", false)
+                    response.put("session", id)
+                }
+                "enter" -> {
+                    check(request.optString("session") == session && session != null && fullscreen.isActive) { "Open the selected Cloud video fullscreen first." }
+                    val owner = requireNotNull(activity)
+                    if (!registered) {
+                        ContextCompat.registerReceiver(owner, receiver, IntentFilter(action), ContextCompat.RECEIVER_NOT_EXPORTED)
+                        registered = true
+                    }
+                    check(owner.enterPictureInPictureMode(params())) { "Picture-in-picture is disabled or unavailable. Check this app's system setting." }
+                    entered = true
+                    response.put("active", true)
+                }
+                "state" -> {
+                    check(request.optString("session") == session && session != null) { "Video session changed." }
+                    playing = request.optBoolean("playing", false)
+                    if (entered) activity?.setPictureInPictureParams(params())
+                }
+                "release" -> {
+                    check(request.optString("session") == session && session != null) { "Video session changed." }
+                    reset()
+                }
+                else -> error("Unsupported Cloud video action.")
+            }
+            Unit
+        }.onFailure { response.put("error", it.message ?: "Picture-in-picture is unavailable.") }
+        proxy.postMessage(response.toString())
+    }
+    fun modeChanged(active: Boolean) {
+        if (active) { entered = true; event("entered") }
+        else if (entered) {
+            entered = false
+            event("restored")
+            // Restoring the viewer is not a stop request. Retire the native
+            // session before Chromium's hide callback can recursively reset it.
+            session = null; reply = null
+            fullscreen.hide()
+        }
+    }
+    fun stopped() { if (entered) { event("command", "pause"); event("closed") } }
+    fun reset() {
+        event("command", "pause")
+        event("closed")
+        session = null; reply = null
+        fullscreen.hide()
+    }
+    fun dispose() {
+        reset()
+        if (registered) runCatching { activity?.unregisterReceiver(receiver) }
+        registered = false
+        webView?.let { view -> bindings[view]?.takeIf { it.owner.get() === this }?.owner?.clear() }
+        webView = null
+    }
+}
+private fun Context.pipActivity(): MainActivity? = when(this) {
+    is MainActivity -> this
+    is ContextWrapper -> baseContext.takeIf { it !== this }?.pipActivity()
+    else -> null
+}
+@Composable
+internal fun rememberCloudVideoPip(fullscreen: WebViewFullscreen): CloudVideoPip {
+    val owner = LocalContext.current.pipActivity()
+    val pip = remember(owner, fullscreen) { CloudVideoPip(owner, fullscreen) }
+    DisposableEffect(pip) {
+        owner?.cloudVideoPip = pip
+        onDispose { if (owner != null && owner.cloudVideoPip === pip) owner.cloudVideoPip = null; pip.dispose() }
+    }
+    return pip
+}

Android/app/src/main/java/com/archipelago/app/ui/screens/CompanionAudioBridge.kt

@@ -0,0 +1,135 @@
+package com.archipelago.app.ui.screens
+
+import android.content.Context
+import android.content.Intent
+import android.net.Uri
+import android.os.SystemClock
+import android.webkit.WebView
+import androidx.core.content.ContextCompat
+import androidx.webkit.JavaScriptReplyProxy
+import androidx.webkit.WebMessageCompat
+import androidx.webkit.WebViewCompat
+import androidx.webkit.WebViewFeature
+import org.json.JSONObject
+import com.archipelago.app.ui.screens.CompanionAudioDiagnostics.Event
+
+/** Metadata/control only: the authorized WebView owns the stream and queue. */
+internal data class CompanionAudioState(
+    val session: String, val sequence: Long, val title: String,
+    val playing: Boolean, val position: Double, val duration: Double,
+    val previous: Boolean, val next: Boolean, val shuffle: Boolean,
+    val shuffled: Boolean, val artwork: String,
+) {
+    companion object {
+        fun parse(value: JSONObject): CompanionAudioState {
+            require(value.optInt("version") == 1 && value.getString("action") == "state")
+            val session = value.getString("session")
+            require(session.matches(Regex("[0-9a-f-]{36}")))
+            val sequence = value.getLong("sequence")
+            require(sequence >= 0 && sequence <= 9007199254740991L)
+            val position = value.getDouble("position"); val duration = value.getDouble("duration")
+            require(position.isFinite() && duration.isFinite() && duration in 0.0..604800.0 && position in 0.0..duration)
+            val title = value.getString("title"); require(title.length <= 512)
+            val artwork = value.optString("artwork", "")
+            require(artwork.length <= 90000 && (artwork.isEmpty() || artwork.startsWith("data:image/jpeg;base64,")))
+            return CompanionAudioState(session, sequence, title, value.getBoolean("playing"), position, duration,
+                value.optBoolean("previous"), value.optBoolean("next"), value.optBoolean("shuffle"),
+                value.optBoolean("shuffled"), artwork)
+        }
+    }
+}
+
+internal object CompanionAudioBridge {
+    private val bindings = java.util.WeakHashMap<WebView, Set<String>>()
+    private val retired = linkedSetOf<String>()
+    private var view: WebView? = null
+    private var origin: String? = null
+    private var reply: ((String) -> Unit)? = null
+    var state: CompanionAudioState? = null
+        private set
+    var updatedAt: Long = 0
+        private set
+    fun retains(web: WebView?) = web != null && view === web && state != null
+    fun attach(web: WebView, urls: List<String>) {
+        if (!WebViewFeature.isFeatureSupported(WebViewFeature.WEB_MESSAGE_LISTENER)) { CompanionAudioDiagnostics.record(Event.BRIDGE_UNSUPPORTED); return }
+        val origins = urls.mapNotNull(::cloudVideoOrigin).toSet()
+        if (origins.isEmpty()) { CompanionAudioDiagnostics.record(Event.NO_APPROVED_ORIGIN); return }
+        val existing = bindings[web]
+        if (existing != null) {
+            if (existing != origins) { CompanionAudioDiagnostics.record(Event.ORIGIN_CHANGED); bindings[web] = emptySet(); release(web) }
+            return
+        }
+        bindings[web] = origins
+        WebViewCompat.addWebMessageListener(web, "ArchipelagoAudio", origins,
+            object : WebViewCompat.WebMessageListener {
+                override fun onPostMessage(web: WebView, message: WebMessageCompat, source: Uri, main: Boolean, proxy: JavaScriptReplyProxy) {
+                    if (bindings[web] != origins) return
+                    val raw = runCatching { message.data }.getOrNull() ?: return
+                    receive(web, raw, source.toString(), main, origins) { proxy.postMessage(it) }
+                }
+            })
+        CompanionAudioDiagnostics.record(Event.BRIDGE_ATTACHED)
+    }
+    internal fun receive(web: WebView, raw: String, source: String, main: Boolean,
+                         origins: Set<String>, proxy: (String) -> Unit) {
+        CompanionAudioDiagnostics.record(Event.MESSAGE_RECEIVED)
+        if (!cloudVideoSenderAllowed(web.url, source, origins, main)) { CompanionAudioDiagnostics.record(Event.SENDER_REJECTED); return }
+        if (raw.length > 96000) { CompanionAudioDiagnostics.record(Event.MESSAGE_TOO_LARGE); return }
+        val data = runCatching { JSONObject(raw) }.getOrNull() ?: run { CompanionAudioDiagnostics.record(Event.INVALID_JSON); return }
+        val session = data.optString("session")
+        if (data.optString("action") == "release") {
+            if (web === view && session == state?.session) { CompanionAudioDiagnostics.record(Event.SESSION_RELEASED); terminate() }
+            return
+        }
+        val incoming = runCatching { CompanionAudioState.parse(data) }.getOrNull() ?: run { CompanionAudioDiagnostics.record(Event.INVALID_STATE); return }
+        if (session in retired) { CompanionAudioDiagnostics.record(Event.RETIRED_SESSION); return }
+        val old = state
+        if (old != null && old.session == session) {
+            if (view !== web || incoming.sequence <= old.sequence) { CompanionAudioDiagnostics.record(Event.STALE_STATE); return }
+        } else {
+            if (!incoming.playing) { CompanionAudioDiagnostics.record(Event.IDLE_STATE); return } // Do not start a service for idle metadata.
+            if (old != null) { command("pause"); retire(old.session) }
+        }
+        CompanionAudioDiagnostics.record(Event.STATE_ACCEPTED)
+        view = web; origin = cloudVideoOrigin(source); reply = proxy
+        state = if (old != null && old.session == session && !data.has("artwork")) incoming.copy(artwork = old.artwork) else incoming; updatedAt = SystemClock.elapsedRealtime()
+        runCatching {
+            val service = CompanionAudioService.instance
+            if (service != null) service.refresh()
+            else {
+                CompanionAudioDiagnostics.record(Event.SERVICE_REQUESTED)
+                ContextCompat.startForegroundService(web.context.applicationContext,
+                    Intent(web.context.applicationContext, CompanionAudioService::class.java))
+            }
+        }.onFailure {
+            CompanionAudioDiagnostics.record(when {
+                it is SecurityException -> Event.SERVICE_PERMISSION_DENIED
+                it.javaClass.simpleName == "ForegroundServiceStartNotAllowedException" -> Event.SERVICE_BACKGROUND_START_DENIED
+                else -> Event.SERVICE_REQUEST_FAILED
+            })
+            event("error", "Background playback could not start. Reopen the companion and press Play.")
+            command("pause"); terminate()
+        }
+    }
+    private fun retire(session: String) {
+        retired.add(session)
+        while (retired.size > 64) retired.remove(retired.first())
+    }
+    private fun event(type: String, value: String? = null, position: Double? = null) {
+        val current = state ?: return
+        if (cloudVideoOrigin(view?.url) != origin) { terminate(); return }
+        val message = JSONObject().put("version", 1).put("session", current.session).put("type", type)
+        if (value != null) message.put(if (type == "error") "error" else "command", value)
+        if (position != null) message.put("position", position)
+        runCatching { reply?.invoke(message.toString()) }
+    }
+    fun command(name: String, position: Double? = null) = event("command", name, position)
+    fun release(web: WebView) { if (view === web) { CompanionAudioDiagnostics.record(Event.PAGE_RELEASED); command("stop"); terminate() } }
+    fun terminate() {
+        state?.session?.let(::retire)
+        state = null; view = null; origin = null; reply = null
+        CompanionAudioService.instance?.finishPlayback()
+        releaseDetachedKioskWebView()
+    }
+    fun stop() { command("stop"); terminate() }
+}

Android/app/src/main/java/com/archipelago/app/ui/screens/CompanionAudioDiagnostics.kt

@@ -0,0 +1,47 @@
+package com.archipelago.app.ui.screens
+
+import android.app.NotificationManager
+import android.content.Context
+import android.os.Build
+import android.os.SystemClock
+import android.webkit.WebView
+
+/** Local, memory-only allowlisted status. Never accepts URLs, titles, IDs, or exception text. */
+internal object CompanionAudioDiagnostics {
+    enum class Event {
+        BRIDGE_ATTACHED, BRIDGE_UNSUPPORTED, NO_APPROVED_ORIGIN, ORIGIN_CHANGED,
+        MESSAGE_RECEIVED, SENDER_REJECTED, MESSAGE_TOO_LARGE, INVALID_JSON, INVALID_STATE,
+        RETIRED_SESSION, STALE_STATE, IDLE_STATE, STATE_ACCEPTED, SERVICE_REQUESTED,
+        SERVICE_REQUEST_FAILED, SERVICE_PERMISSION_DENIED, SERVICE_BACKGROUND_START_DENIED, SERVICE_CREATED, SERVICE_STARTED, FOREGROUND_ACTIVE,
+        SERVICE_FINISHED, SERVICE_DESTROYED, PAGE_RELEASED, SESSION_RELEASED, HEARTBEAT_EXPIRED,
+    }
+    private val counts = linkedMapOf<Event, Long>()
+    private val recent = ArrayDeque<Pair<Long, Event>>()
+    @Synchronized fun record(event: Event) {
+        counts[event] = (counts[event] ?: 0) + 1
+        // Position updates must not displace the useful startup/failure sequence.
+        if (recent.lastOrNull()?.second != event && event !in setOf(Event.MESSAGE_RECEIVED, Event.STATE_ACCEPTED, Event.FOREGROUND_ACTIVE)) {
+            recent.addLast(SystemClock.elapsedRealtime() to event)
+            while (recent.size > 12) recent.removeFirst()
+        }
+    }
+    @Synchronized internal fun events(): String = buildString {
+        counts.forEach { (event, count) -> append("${event.name}: $count\n") }
+        append("Recent transitions (seconds since boot):\n")
+        recent.forEach { (at, event) -> append("${at / 1000}: ${event.name}\n") }
+    }
+    fun report(context: Context): String = buildString {
+        val manager = context.getSystemService(NotificationManager::class.java)
+        append("Companion playback diagnostics v1\n")
+        val app = context.packageManager.getPackageInfo(context.packageName, 0)
+        append("App: ${app.versionName}\n")
+        append("Android API: ${Build.VERSION.SDK_INT}\n")
+        append("WebView: ${WebView.getCurrentWebViewPackage()?.versionName ?: "unavailable"}\n")
+        append("Notifications enabled: ${manager.areNotificationsEnabled()}\n")
+        append("Audio channel importance: ${manager.getNotificationChannel("companion-audio")?.importance ?: "not created"}\n")
+        append("Native session: ${CompanionAudioBridge.state != null}\n")
+        append("Native playing: ${CompanionAudioBridge.state?.playing ?: false}\n")
+        append("Service present: ${CompanionAudioService.instance != null}\n")
+        append(events())
+    }
+}

Android/app/src/main/java/com/archipelago/app/ui/screens/CompanionAudioService.kt

@@ -0,0 +1,177 @@
+package com.archipelago.app.ui.screens
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.app.Service
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.media.AudioManager
+import android.media.MediaMetadata
+import android.media.session.MediaSession
+import android.media.session.PlaybackState
+import android.os.Bundle
+import android.os.Handler
+import android.os.IBinder
+import android.os.Looper
+import android.os.SystemClock
+import android.util.Base64
+import androidx.core.content.ContextCompat
+import com.archipelago.app.MainActivity
+import com.archipelago.app.ui.screens.CompanionAudioDiagnostics.Event
+
+/** Foreground ownership of the existing authenticated WebView player. No stream
+ * URL, auth token or cookie is copied into native playback or notifications. */
+class CompanionAudioService : Service() {
+    companion object {
+        internal var instance: CompanionAudioService? = null
+        private const val CHANNEL = "companion-audio"
+        private const val NOTIFICATION = 4056
+    }
+    private lateinit var media: MediaSession
+    private val handler = Handler(Looper.getMainLooper())
+    private var lastArtwork = ""
+    private var bitmap: Bitmap? = null
+    private var finishing = false
+    private val noisy = object : BroadcastReceiver() {
+        override fun onReceive(context: Context?, intent: Intent?) {
+            if (intent?.action == AudioManager.ACTION_AUDIO_BECOMING_NOISY) CompanionAudioBridge.command("pause")
+        }
+    }
+    private val watchdog = object : Runnable {
+        override fun run() {
+            val state = CompanionAudioBridge.state ?: return
+            val age = SystemClock.elapsedRealtime() - CompanionAudioBridge.updatedAt
+            if (age > 90000) { CompanionAudioDiagnostics.record(Event.HEARTBEAT_EXPIRED); CompanionAudioBridge.stop() }
+            else {
+                if (age > 15000) CompanionAudioBridge.command("sync")
+                handler.postDelayed(this, 5000)
+            }
+        }
+    }
+    override fun onCreate() {
+        super.onCreate(); instance = this
+        CompanionAudioDiagnostics.record(Event.SERVICE_CREATED)
+        getSystemService(NotificationManager::class.java).createNotificationChannel(
+            NotificationChannel(CHANNEL, "Audio playback", NotificationManager.IMPORTANCE_LOW))
+        media = MediaSession(this, "Archipelago audio")
+        media.setCallback(object : MediaSession.Callback() {
+            override fun onPlay() = CompanionAudioBridge.command("play")
+            override fun onPause() = CompanionAudioBridge.command("pause")
+            override fun onStop() = CompanionAudioBridge.stop()
+            override fun onSkipToNext() { if (CompanionAudioBridge.state?.next == true) CompanionAudioBridge.command("next") }
+            override fun onSkipToPrevious() { if (CompanionAudioBridge.state?.previous == true) CompanionAudioBridge.command("previous") }
+            override fun onSeekTo(pos: Long) {
+                val duration = CompanionAudioBridge.state?.duration ?: return
+                CompanionAudioBridge.command("seek", (pos / 1000.0).coerceIn(0.0, duration))
+            }
+            override fun onCustomAction(action: String, extras: Bundle?) {
+                if (action == "shuffle" && CompanionAudioBridge.state?.shuffle == true) CompanionAudioBridge.command("shuffle")
+            }
+        }, handler)
+        media.setFlags(MediaSession.FLAG_HANDLES_MEDIA_BUTTONS or MediaSession.FLAG_HANDLES_TRANSPORT_CONTROLS)
+        media.setSessionActivity(openPlayer())
+        media.isActive = true
+        ContextCompat.registerReceiver(this, noisy, IntentFilter(AudioManager.ACTION_AUDIO_BECOMING_NOISY), ContextCompat.RECEIVER_NOT_EXPORTED)
+        handler.postDelayed(watchdog, 5000)
+    }
+    override fun onBind(intent: Intent?): IBinder? = null
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        CompanionAudioDiagnostics.record(Event.SERVICE_STARTED)
+        val state = CompanionAudioBridge.state
+        if (state == null) { finishPlayback(); return START_NOT_STICKY }
+        finishing = false; instance = this
+        if (intent?.action != null && intent.getStringExtra("session") == state.session) {
+            when (intent.action) {
+                "stop" -> CompanionAudioBridge.stop()
+                "play", "pause" -> CompanionAudioBridge.command(intent.action!!)
+                "next" -> if (state.next) CompanionAudioBridge.command("next")
+                "previous" -> if (state.previous) CompanionAudioBridge.command("previous")
+                "shuffle" -> if (state.shuffle) CompanionAudioBridge.command("shuffle")
+            }
+        }
+        if (!finishing) refresh()
+        return START_NOT_STICKY // Never reconstruct an authorized stream after process death.
+    }
+    private fun openPlayer() = PendingIntent.getActivity(this, 0,
+        Intent(this, MainActivity::class.java).addFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP),
+        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE)
+    private fun action(name: String, label: String, icon: Int, session: String): Notification.Action {
+        val intent = Intent(this, CompanionAudioService::class.java).setAction(name).putExtra("session", session)
+        val pending = PendingIntent.getService(this, name.hashCode(), intent, PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE)
+        return Notification.Action.Builder(icon, label, pending).build()
+    }
+    internal fun refresh() {
+        if (finishing) return
+        val state = CompanionAudioBridge.state ?: return
+        if (state.artwork != lastArtwork) {
+            lastArtwork = state.artwork
+            bitmap = decodeArtwork(state.artwork)
+        }
+        val metadata = MediaMetadata.Builder().putString(MediaMetadata.METADATA_KEY_TITLE, state.title)
+            .putString(MediaMetadata.METADATA_KEY_ARTIST, "Archipelago")
+            .putLong(MediaMetadata.METADATA_KEY_DURATION, (state.duration * 1000).toLong())
+        bitmap?.let { metadata.putBitmap(MediaMetadata.METADATA_KEY_ALBUM_ART, it) }
+        media.setMetadata(metadata.build())
+        var actions = PlaybackState.ACTION_PLAY or PlaybackState.ACTION_PAUSE or PlaybackState.ACTION_PLAY_PAUSE or PlaybackState.ACTION_STOP
+        if (state.duration > 0) actions = actions or PlaybackState.ACTION_SEEK_TO
+        if (state.previous) actions = actions or PlaybackState.ACTION_SKIP_TO_PREVIOUS
+        if (state.next) actions = actions or PlaybackState.ACTION_SKIP_TO_NEXT
+        val playback = PlaybackState.Builder().setActions(actions)
+            .setState(if (state.playing) PlaybackState.STATE_PLAYING else PlaybackState.STATE_PAUSED,
+                (state.position * 1000).toLong(), if (state.playing) 1f else 0f, SystemClock.elapsedRealtime())
+        if (state.shuffle) playback.addCustomAction("shuffle", if (state.shuffled) "Shuffle on" else "Shuffle off", android.R.drawable.ic_menu_rotate)
+        media.setPlaybackState(playback.build())
+        val controls = mutableListOf<Notification.Action>()
+        if (state.previous) controls.add(action("previous", "Previous", android.R.drawable.ic_media_previous, state.session))
+        controls.add(action(if (state.playing) "pause" else "play", if (state.playing) "Pause" else "Play",
+            if (state.playing) android.R.drawable.ic_media_pause else android.R.drawable.ic_media_play, state.session))
+        if (state.next) controls.add(action("next", "Next", android.R.drawable.ic_media_next, state.session))
+        val compact = controls.indices.toList().toIntArray()
+        if (state.shuffle) controls.add(action("shuffle", if (state.shuffled) "Shuffle on" else "Shuffle off", android.R.drawable.ic_menu_rotate, state.session))
+        controls.add(action("stop", "Stop", android.R.drawable.ic_menu_close_clear_cancel, state.session))
+        val notification = Notification.Builder(this, CHANNEL)
+            .setSmallIcon(android.R.drawable.ic_media_play).setContentTitle(state.title).setContentText("Archipelago")
+            .setContentIntent(openPlayer()).setOnlyAlertOnce(true).setOngoing(state.playing)
+            .setVisibility(Notification.VISIBILITY_PUBLIC).setCategory(Notification.CATEGORY_TRANSPORT)
+            .setStyle(Notification.MediaStyle().setMediaSession(media.sessionToken).setShowActionsInCompactView(*compact))
+            .setActions(*controls.toTypedArray())
+        bitmap?.let { notification.setLargeIcon(it) }
+        startForeground(NOTIFICATION, notification.build())
+        CompanionAudioDiagnostics.record(Event.FOREGROUND_ACTIVE)
+    }
+    override fun onTaskRemoved(rootIntent: Intent?) {
+        if (CompanionAudioBridge.state?.playing != true) CompanionAudioBridge.stop()
+        super.onTaskRemoved(rootIntent)
+    }
+    internal fun finishPlayback() {
+        if (finishing) return
+        finishing = true
+        CompanionAudioDiagnostics.record(Event.SERVICE_FINISHED)
+        if (instance === this) instance = null
+        stopForeground(STOP_FOREGROUND_REMOVE); stopSelf()
+    }
+    override fun onDestroy() {
+        CompanionAudioDiagnostics.record(Event.SERVICE_DESTROYED)
+        handler.removeCallbacksAndMessages(null)
+        runCatching { unregisterReceiver(noisy) }
+        media.isActive = false; media.release(); bitmap = null
+        if (instance === this) { instance = null; CompanionAudioBridge.stop() }
+        super.onDestroy()
+    }
+}
+
+internal fun decodeArtwork(data: String): Bitmap? = runCatching {
+    if (!data.startsWith("data:image/jpeg;base64,") || data.length > 90000) return null
+    val bytes = Base64.decode(data.substringAfter(','), Base64.NO_WRAP)
+    if (bytes.size < 4 || bytes[0] != 0xff.toByte() || bytes[1] != 0xd8.toByte() || bytes[2] != 0xff.toByte()) return null
+    val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+    BitmapFactory.decodeByteArray(bytes, 0, bytes.size, bounds)
+    if (bounds.outWidth !in 1..512 || bounds.outHeight !in 1..512) return null
+    BitmapFactory.decodeByteArray(bytes, 0, bytes.size)
+}.getOrNull()

Android/app/src/main/java/com/archipelago/app/ui/screens/WebViewDownloads.kt

@@ -0,0 +1,179 @@
+package com.archipelago.app.ui.screens
+
+import android.app.Activity
+import android.content.Intent
+import android.net.Uri
+import android.provider.DocumentsContract
+import android.webkit.CookieManager
+import android.webkit.DownloadListener
+import android.webkit.URLUtil
+import android.widget.Toast
+import androidx.activity.compose.rememberLauncherForActivityResult
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.compose.foundation.layout.Column
+import androidx.compose.material3.AlertDialog
+import androidx.compose.material3.LinearProgressIndicator
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.*
+import androidx.compose.ui.platform.LocalContext
+import kotlinx.coroutines.*
+import okhttp3.Call
+import okhttp3.HttpUrl.Companion.toHttpUrlOrNull
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import java.io.IOException
+import java.io.OutputStream
+import java.util.concurrent.TimeUnit
+
+internal data class WebDownload(val url: String, val userAgent: String, val cookies: String, val name: String, val mime: String)
+
+/** Only the starting origin receives its WebView cookies, even across redirects. */
+internal fun streamWebDownload(
+    download: WebDownload,
+    output: OutputStream,
+    client: OkHttpClient,
+    onCall: (Call) -> Unit = {},
+    checkCancelled: () -> Unit = {},
+    onProgress: (Long, Long) -> Unit = { _, _ -> },
+): Long {
+    val transport = client.newBuilder().followRedirects(false).followSslRedirects(false).build()
+    val original = download.url.toHttpUrlOrNull() ?: throw IOException("Unsupported download link")
+    var url = original
+    var redirects = 0
+    while (true) {
+        checkCancelled()
+        if (url.username.isNotEmpty() || url.password.isNotEmpty()) throw IOException("Unsupported download link")
+        val request = Request.Builder().url(url).header("User-Agent", download.userAgent)
+        if (url.scheme == original.scheme && url.host == original.host && url.port == original.port && download.cookies.isNotBlank()) {
+            request.header("Cookie", download.cookies)
+        }
+        val call = transport.newCall(request.build())
+        onCall(call)
+        call.execute().use { response ->
+            if (response.code in listOf(301, 302, 303, 307, 308)) {
+                if (++redirects > 5) throw IOException("Too many download redirects")
+                val next = response.header("Location")?.let { url.resolve(it) } ?: throw IOException("Invalid download redirect")
+                if (url.isHttps && !next.isHttps) throw IOException("Insecure download redirect blocked")
+                url = next
+            } else {
+                if (response.code == 401 || response.code == 403) throw IOException("Sign in to the node again, then retry the download")
+                if (!response.isSuccessful) throw IOException("Download failed (HTTP ${response.code})")
+                if (response.header("Content-Type")?.substringBefore(';')?.trim()?.lowercase() == "text/html" &&
+                    download.mime != "text/html" && !download.name.endsWith(".html", true) && !download.name.endsWith(".htm", true)) {
+                    throw IOException("Sign in to the node again, then retry the download")
+                }
+                val body = response.body ?: throw IOException("The download was empty")
+                val total = body.contentLength()
+                var written = 0L
+                body.byteStream().use { input ->
+                    val buffer = ByteArray(64 * 1024)
+                    var lastUpdate = 0L
+                    while (true) {
+                        checkCancelled()
+                        val count = input.read(buffer)
+                        if (count == -1) break
+                        output.write(buffer, 0, count)
+                        written += count
+                        val now = System.nanoTime()
+                        if (now - lastUpdate > 100_000_000L) { onProgress(written, total); lastUpdate = now }
+                    }
+                }
+                if (total >= 0 && written != total) throw IOException("Download interrupted; please retry")
+                onProgress(written, total)
+                return written
+            }
+        }
+    }
+}
+
+/** Uses the system Save dialog: no broad storage permission and no external browser login. */
+@Composable
+internal fun rememberWebViewDownloads(): DownloadListener {
+    val context = LocalContext.current
+    val scope = rememberCoroutineScope()
+    var pending by remember { mutableStateOf<WebDownload?>(null) }
+    var active by remember { mutableStateOf<WebDownload?>(null) }
+    var progress by remember { mutableStateOf<Pair<Long, Long>>(0L to -1L) }
+    var failure by remember { mutableStateOf<String?>(null) }
+    var job by remember { mutableStateOf<Job?>(null) }
+    val currentCall = remember { java.util.concurrent.atomic.AtomicReference<Call?>(null) }
+    val client = remember {
+        OkHttpClient.Builder().followRedirects(false).followSslRedirects(false)
+            .connectTimeout(20, TimeUnit.SECONDS).readTimeout(60, TimeUnit.SECONDS).build()
+    }
+    fun cancel() { job?.cancel(); currentCall.getAndSet(null)?.cancel() }
+    DisposableEffect(Unit) { onDispose { currentCall.getAndSet(null)?.cancel() } }
+    val save = rememberLauncherForActivityResult(ActivityResultContracts.StartActivityForResult()) { result ->
+        val download = pending
+        pending = null
+        val uri = result.data?.data
+        if (result.resultCode != Activity.RESULT_OK || uri == null || download == null) return@rememberLauncherForActivityResult
+        job = scope.launch {
+            active = download
+            progress = 0L to -1L
+            var complete = false
+            try {
+                withContext(Dispatchers.IO) {
+                    val task = currentCoroutineContext()
+                    context.contentResolver.openOutputStream(uri, "w")?.use { output ->
+                        streamWebDownload(download, output, client,
+                            onCall = { call -> currentCall.set(call); if (!task.isActive) call.cancel() },
+                            checkCancelled = { task.ensureActive() },
+                            onProgress = { done, total -> scope.launch { progress = done to total } })
+                    } ?: throw IOException("Unable to open the selected destination")
+                }
+                complete = true
+                Toast.makeText(context, "Download complete: ${download.name}", Toast.LENGTH_LONG).show()
+            } catch (error: CancellationException) {
+                throw error
+            } catch (error: Exception) {
+                if (currentCoroutineContext().isActive) {
+                    // Do not expose authenticated URLs or request headers in UI/logs.
+                    failure = when {
+                        error is javax.net.ssl.SSLException -> "The server certificate could not be verified."
+                        error is IOException && error.message?.startsWith("Sign in") == true -> error.message
+                        else -> "Download failed. Check your connection and available storage, then try again."
+                    }
+                }
+            } finally {
+                currentCall.getAndSet(null)?.cancel()
+                if (!complete) withContext(NonCancellable + Dispatchers.IO) {
+                    // This URI was newly created by ACTION_CREATE_DOCUMENT; never remove an existing user file.
+                    runCatching { DocumentsContract.deleteDocument(context.contentResolver, uri) }
+                }
+                active = null
+                job = null
+            }
+        }
+    }
+    if (active != null) {
+        AlertDialog(onDismissRequest = {}, title = { Text("Downloading") }, text = {
+            Column {
+                Text(active!!.name)
+                if (progress.second > 0) LinearProgressIndicator(progress = (progress.first.toFloat() / progress.second).coerceIn(0f, 1f))
+                else LinearProgressIndicator()
+            }
+        }, confirmButton = {}, dismissButton = { TextButton(onClick = { cancel() }) { Text("Cancel") } })
+    }
+    failure?.let { message ->
+        AlertDialog(onDismissRequest = { failure = null }, title = { Text("Download unavailable") },
+            text = { Text(message) }, confirmButton = { TextButton(onClick = { failure = null }) { Text("OK") } })
+    }
+    return DownloadListener { url, userAgent, disposition, mimeType, _ ->
+        if (active != null || pending != null) {
+            Toast.makeText(context, "Finish or cancel the current download first", Toast.LENGTH_SHORT).show()
+        } else if (url.toHttpUrlOrNull() == null) {
+            failure = "This download link is not supported. Open the file from Cloud and try again."
+        } else {
+            val mime = mimeType?.substringBefore(';')?.takeIf { it.contains('/') } ?: "application/octet-stream"
+            val name = URLUtil.guessFileName(url, disposition, mime).replace(Regex("[\\\\/\\p{Cntrl}]"), "_").take(180).ifBlank { "download" }
+            pending = WebDownload(url, userAgent ?: "Archipelago Companion", CookieManager.getInstance().getCookie(url).orEmpty(), name, mime)
+            try {
+                save.launch(Intent(Intent.ACTION_CREATE_DOCUMENT).apply {
+                    addCategory(Intent.CATEGORY_OPENABLE); type = mime; putExtra(Intent.EXTRA_TITLE, name)
+                })
+            } catch (_: Exception) { pending = null; failure = "No file-saving app is available on this device." }
+        }
+    }
+}

Android/app/src/main/java/com/archipelago/app/ui/screens/WebViewFullscreen.kt

@@ -0,0 +1,117 @@
+package com.archipelago.app.ui.screens
+
+import android.content.Context
+import android.content.ContextWrapper
+import android.graphics.Color
+import android.view.View
+import android.view.ViewGroup
+import android.webkit.WebChromeClient
+import android.widget.FrameLayout
+import androidx.activity.ComponentActivity
+import androidx.activity.OnBackPressedCallback
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.remember
+import androidx.compose.ui.platform.LocalContext
+import androidx.core.view.ViewCompat
+import androidx.core.view.WindowCompat
+import androidx.core.view.WindowInsetsCompat
+import androidx.core.view.WindowInsetsControllerCompat
+
+private fun Context.fullscreenActivity(): ComponentActivity? = when (this) {
+    is ComponentActivity -> this
+    is ContextWrapper -> baseContext.takeIf { it !== this }?.fullscreenActivity()
+    else -> null
+}
+
+/** Hosts Chromium's custom fullscreen view without replacing or reloading its WebView. */
+internal class WebViewFullscreen(private val activity: ComponentActivity?) {
+    private var overlay: FrameLayout? = null
+    private var callback: WebChromeClient.CustomViewCallback? = null
+    private var back: OnBackPressedCallback? = null
+    val isActive: Boolean get() = overlay != null
+    fun bounds(rect: android.graphics.Rect): Boolean = overlay?.getGlobalVisibleRect(rect) == true
+    private var visibleBars = 0
+    private var originalBehavior = 0
+
+    fun show(view: View?, onHidden: WebChromeClient.CustomViewCallback?) {
+        val owner = activity
+        // A second enter must not detach the active video or strand its callback.
+        if (owner == null || owner.isFinishing || owner.isDestroyed || view == null ||
+            view.parent != null || overlay != null
+        ) {
+            onHidden?.onCustomViewHidden()
+            return
+        }
+        val decor = owner.window.decorView as? ViewGroup
+        if (decor == null) { onHidden?.onCustomViewHidden(); return }
+        val controller = WindowCompat.getInsetsController(owner.window, decor)
+        val insets = ViewCompat.getRootWindowInsets(decor)
+        visibleBars = 0
+        if (insets?.isVisible(WindowInsetsCompat.Type.statusBars()) != false) {
+            visibleBars = visibleBars or WindowInsetsCompat.Type.statusBars()
+        }
+        if (insets?.isVisible(WindowInsetsCompat.Type.navigationBars()) != false) {
+            visibleBars = visibleBars or WindowInsetsCompat.Type.navigationBars()
+        }
+        originalBehavior = controller.systemBarsBehavior
+        val host = FrameLayout(owner).apply {
+            setBackgroundColor(Color.BLACK)
+            keepScreenOn = true
+            addView(view, FrameLayout.LayoutParams(-1, -1))
+        }
+        overlay = host
+        callback = onHidden
+        decor.addView(host, ViewGroup.LayoutParams(-1, -1))
+        controller.systemBarsBehavior = WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE
+        controller.hide(WindowInsetsCompat.Type.systemBars())
+        back = object : OnBackPressedCallback(true) {
+            override fun handleOnBackPressed() = hide()
+        }.also { owner.onBackPressedDispatcher.addCallback(it) }
+        view.requestFocus()
+    }
+
+    fun hide() {
+        val host = overlay ?: return
+        if (activity?.isInPictureInPictureMode == true) {
+            // A navigation/logout/custom-view exit must never expose the node
+            // management UI in the small OS window. Keep a black cover until
+            // the activity leaves PiP; the ordinary hide then removes it.
+            val notify = callback; callback = null
+            back?.remove(); back = null
+            host.keepScreenOn = false; host.removeAllViews()
+            host.addView(android.widget.TextView(host.context).apply {
+                text = "Video paused. Expand to return."
+                setTextColor(Color.WHITE)
+                gravity = android.view.Gravity.CENTER
+                contentDescription = "Video paused. Use picture-in-picture controls to expand or close."
+            }, FrameLayout.LayoutParams(-1, -1))
+            notify?.onCustomViewHidden()
+            return
+        }
+        // Clear first: Chromium may synchronously call onHideCustomView again.
+        overlay = null
+        val notify = callback
+        callback = null
+        back?.remove()
+        back = null
+        host.keepScreenOn = false
+        host.removeAllViews()
+        (host.parent as? ViewGroup)?.removeView(host)
+        activity?.let { owner ->
+            val controller = WindowCompat.getInsetsController(owner.window, owner.window.decorView)
+            controller.systemBarsBehavior = originalBehavior
+            controller.hide(WindowInsetsCompat.Type.systemBars())
+            if (visibleBars != 0) controller.show(visibleBars)
+        }
+        notify?.onCustomViewHidden()
+    }
+}
+
+@Composable
+internal fun rememberWebViewFullscreen(): WebViewFullscreen {
+    val context = LocalContext.current
+    val fullscreen = remember(context) { WebViewFullscreen(context.fullscreenActivity()) }
+    DisposableEffect(fullscreen) { onDispose { fullscreen.hide() } }
+    return fullscreen
+}

Android/app/src/main/java/com/archipelago/app/ui/screens/WebViewScreen.kt

@@ -144,6 +144,29 @@ private fun openExternalUrl(context: android.content.Context, url: String) {
  *  this when the task is genuinely finishing. */
 fun releaseKioskWebView() = KioskWebView.drop()
 
+/** A playing session is owned by the foreground media service after task close. */
+fun finishKioskActivity() {
+    val view = KioskWebView.instance ?: return
+    if (!CompanionAudioBridge.retains(view)) { KioskWebView.drop(); return }
+    (view.parent as? ViewGroup)?.removeView(view)
+    KioskWebView.backgroundOwned = true
+    KioskWebView.clearDelegates()
+    view.setOnTouchListener(null)
+    view.setOnApplyWindowInsetsListener(null)
+    view.setDownloadListener(null)
+    view.webChromeClient = null
+    view.webViewClient = object : WebViewClient() {
+        override fun onPageStarted(web: WebView?, url: String?, favicon: Bitmap?) {
+            web?.let { CompanionAudioBridge.release(it) }
+        }
+    }
+    (view.context as? android.content.MutableContextWrapper)?.baseContext = view.context.applicationContext
+}
+
+internal fun releaseDetachedKioskWebView() {
+    if (KioskWebView.backgroundOwned && !CompanionAudioBridge.retains(KioskWebView.instance)) KioskWebView.drop()
+}
+
 /** Restart the app in place: throw away the retained page and relaunch the
  *  task from scratch. The mesh/VPN service is deliberately left running — this
  *  is the "give me a clean app" button (hub menu), not a process kill. */
@@ -294,6 +317,7 @@ private fun isSameHost(url: String, base: String): Boolean {
 data class InAppLaunch(val url: String, val icon: String? = null, val name: String? = null)
 
 private object KioskWebView {
+    var backgroundOwned = false
     var instance: WebView? = null
     var url: String? = null
 
@@ -306,13 +330,19 @@ private object KioskWebView {
     var onQrStatus: (String, Boolean) -> Unit = { _, _ -> }
     var onQrClose: () -> Unit = {}
 
+    fun clearDelegates() {
+        onRouteOutbound = {}; onOpenInApp = {}; onQrOpen = {}
+        onQrStatus = { _, _ -> }; onQrClose = {}
+    }
     fun drop() {
-        instance?.let {
+        val old = instance
+        instance = null; url = null; backgroundOwned = false
+        clearDelegates()
+        old?.let {
+            CompanionAudioBridge.release(it)
             (it.parent as? ViewGroup)?.removeView(it)
             it.destroy()
         }
-        instance = null
-        url = null
     }
 }
 
@@ -611,6 +641,9 @@ fun WebViewScreen(
     // before surfacing the error page: the mesh tunnel works from anywhere.
     meshFallbackUrl: String? = null,
 ) {
+    val fullscreen = rememberWebViewFullscreen()
+    val cloudPip = rememberCloudVideoPip(fullscreen)
+    val downloads = rememberWebViewDownloads()
     var isLoading by remember { mutableStateOf(true) }
     // First kiosk load (often over the FIPS mesh) gets the full branded
     // loader; later navigations keep just the slim top progress bar.
@@ -898,7 +931,9 @@ fun WebViewScreen(
                     // stale closures from the previous visit are replaced.
                     if (KioskWebView.url != serverUrl) KioskWebView.drop()
                     val reused = KioskWebView.instance
-                    (reused ?: WebView(context)).apply {
+                    (reused ?: WebView(android.content.MutableContextWrapper(context))).apply {
+                        (this.context as? android.content.MutableContextWrapper)?.baseContext = context
+                        KioskWebView.backgroundOwned = false
                         (parent as? ViewGroup)?.removeView(this)
                         layoutParams = ViewGroup.LayoutParams(
                             ViewGroup.LayoutParams.MATCH_PARENT,
@@ -913,6 +948,9 @@ fun WebViewScreen(
                         cookieManager.setAcceptThirdPartyCookies(this, true)
 
                         applyArchipelagoSettings()
+                        cloudPip.attach(this, listOfNotNull(serverUrl, meshFallbackUrl))
+                        CompanionAudioBridge.attach(this, listOfNotNull(serverUrl, meshFallbackUrl))
+                        setDownloadListener(downloads)
                         settings.apply {
                             setSupportMultipleWindows(true)  // enables onCreateWindow for window.open
                             // Let JS open windows without a synchronous user-gesture
@@ -1086,6 +1124,8 @@ fun WebViewScreen(
 
                         webViewClient = object : WebViewClient() {
                             override fun onPageStarted(view: WebView?, url: String?, favicon: Bitmap?) {
+                                CompanionAudioBridge.release(view ?: return)
+                                cloudPip.reset()
                                 isLoading = true
                                 hasError = false
                                 // New document — the injected safe-area style is
@@ -1181,6 +1221,12 @@ fun WebViewScreen(
                         }
 
                         webChromeClient = object : WebChromeClient() {
+                            override fun onShowCustomView(view: android.view.View?, callback: CustomViewCallback?) {
+                                fullscreen.show(view, callback)
+                            }
+
+                            override fun onHideCustomView() { cloudPip.reset(); fullscreen.hide() }
+
                             override fun onProgressChanged(view: WebView?, newProgress: Int) {
                                 loadProgress = newProgress
                             }
@@ -1546,6 +1592,8 @@ private fun InAppBrowser(
     appName: String? = null,
     onClose: () -> Unit,
 ) {
+    val fullscreen = rememberWebViewFullscreen()
+    val downloads = rememberWebViewDownloads()
     val context = LocalContext.current
     // Same-node check across BOTH node addresses (LAN + mesh ULA) — see the
     // kiosk's isSameNode; a mismatch here bounced app links to the browser.
@@ -1643,6 +1691,7 @@ private fun InAppBrowser(
 
                         CookieManager.getInstance().setAcceptThirdPartyCookies(this, true)
                         applyArchipelagoSettings()
+                        setDownloadListener(downloads)
                         // Node apps (BTCPay invoices, LND, Portainer tokens) are
                         // served over plain HTTP too — same dead-clipboard trap.
                         addClipboardBridge()
@@ -1662,6 +1711,12 @@ private fun InAppBrowser(
                         )
 
                         webChromeClient = object : WebChromeClient() {
+                            override fun onShowCustomView(view: android.view.View?, callback: CustomViewCallback?) {
+                                fullscreen.show(view, callback)
+                            }
+
+                            override fun onHideCustomView() = fullscreen.hide()
+
                             override fun onProgressChanged(view: WebView?, newProgress: Int) {
                                 progress = newProgress
                             }

Android/app/src/test/java/com/archipelago/app/ui/screens/CloudVideoPipTest.kt

@@ -0,0 +1,26 @@
+package com.archipelago.app.ui.screens
+
+import org.junit.Assert.*
+import org.junit.Test
+
+class CloudVideoPipTest {
+    @Test fun nativeChannelRejectsSiblingFrameAndStaleOrForeignPage() {
+        val allowed = setOf("https://node.test", "http://[fd00::1]")
+        assertTrue(cloudVideoSenderAllowed("https://node.test/cloud", "https://node.test", allowed, true))
+        assertFalse(cloudVideoSenderAllowed("https://node.test/cloud", "https://node.test", allowed, false))
+        assertFalse(cloudVideoSenderAllowed("https://other.test", "https://node.test", allowed, true))
+        assertFalse(cloudVideoSenderAllowed("https://node.test:7778", "https://node.test:7778", allowed, true))
+        assertFalse(cloudVideoSenderAllowed("https://node.test", "http://node.test", allowed, true))
+    }
+
+    @Test fun exactOriginIncludesSchemeAndNonDefaultPort() {
+        assertEquals("https://node.test", cloudVideoOrigin("https://NODE.test:443/cloud"))
+        assertEquals("http://node.test:8080", cloudVideoOrigin("http://node.test:8080/cloud?file=video"))
+        assertEquals("http://[fd00::1]", cloudVideoOrigin("http://[fd00::1]/cloud"))
+        assertNotEquals(cloudVideoOrigin("https://node.test"), cloudVideoOrigin("http://node.test"))
+        assertNotEquals(cloudVideoOrigin("https://node.test"), cloudVideoOrigin("https://node.test:7778"))
+    }
+    @Test fun unsupportedAndCredentialOriginsCannotReceiveBridge() {
+        for (url in listOf("javascript:alert(1)", "file:///video", "data:text/plain,video", "https://user:password@node.test/video", "not-a-url")) assertNull(cloudVideoOrigin(url))
+    }
+}

Android/app/src/test/java/com/archipelago/app/ui/screens/CompanionAudioTest.kt

@@ -0,0 +1,157 @@
+package com.archipelago.app.ui.screens
+
+import org.json.JSONObject
+import org.junit.Assert.*
+import org.junit.Test
+import org.junit.Before
+import org.robolectric.Shadows
+import org.robolectric.RuntimeEnvironment
+import org.junit.runner.RunWith
+import org.robolectric.Robolectric
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+@RunWith(RobolectricTestRunner::class)
+@Config(manifest = Config.NONE, sdk = [28, 35])
+class CompanionAudioTest {
+    @Before fun compatReceiverPermission() {
+        val app = RuntimeEnvironment.getApplication()
+        // The real merged manifest contributes this AndroidX permission.
+        Shadows.shadowOf(app).grantPermissions(app.packageName + ".DYNAMIC_RECEIVER_NOT_EXPORTED_PERMISSION")
+    }
+    @Test fun actualBridgeBindsOriginSessionAndSequenceAndReleasesStoppedPlayback() {
+        val app = RuntimeEnvironment.getApplication()
+        val web = android.webkit.WebView(app)
+        web.loadUrl("https://node.test/cloud")
+        val events = mutableListOf<JSONObject>()
+        fun send(message: JSONObject, origin: String = "https://node.test", main: Boolean = true) {
+            CompanionAudioBridge.receive(web, message.toString(), origin, main, setOf("https://node.test")) { events.add(JSONObject(it)) }
+        }
+        try {
+            send(state(), main = false); assertNull(CompanionAudioBridge.state)
+            send(state(), origin = "https://foreign.test"); assertNull(CompanionAudioBridge.state)
+            send(state()); assertTrue(CompanionAudioBridge.retains(web))
+            send(state().put("sequence", 0).put("playing", false)); assertTrue(CompanionAudioBridge.state!!.playing)
+            CompanionAudioBridge.command("seek", 32.0)
+            assertEquals("seek", events.last().getString("command")); assertEquals(32.0, events.last().getDouble("position"), 0.0)
+            send(state().put("sequence", 2).put("playing", false)); assertFalse(CompanionAudioBridge.state!!.playing)
+            CompanionAudioBridge.stop(); assertNull(CompanionAudioBridge.state)
+            assertEquals("stop", events.last().getString("command"))
+            send(state().put("sequence", 3)); assertNull(CompanionAudioBridge.state) // delayed state cannot revive a stopped session
+        } finally { CompanionAudioBridge.release(web); web.destroy() }
+    }
+    @Test fun liveBridgeBuildsForegroundMediaNotificationForSameSession() {
+        val app = RuntimeEnvironment.getApplication()
+        val web = android.webkit.WebView(app); web.loadUrl("https://node.test/cloud")
+        val payload = state().put("session", "22345678-1234-1234-1234-123456789abc")
+        CompanionAudioBridge.receive(web, payload.toString(), "https://node.test", true, setOf("https://node.test")) {}
+        val lifecycle = Robolectric.buildService(CompanionAudioService::class.java).create()
+        try {
+            lifecycle.get().onStartCommand(null, 0, 1)
+            val notification = Shadows.shadowOf(lifecycle.get()).lastForegroundNotification
+            assertNotNull(notification)
+            assertEquals("Current song", notification.extras.getString(android.app.Notification.EXTRA_TITLE))
+            assertEquals(5, notification.actions.size)
+            assertNotNull(notification.extras.getParcelable<android.media.session.MediaSession.Token>(android.app.Notification.EXTRA_MEDIA_SESSION))
+            lifecycle.get().onTaskRemoved(null)
+            assertTrue(CompanionAudioBridge.retains(web))
+        } finally { CompanionAudioBridge.release(web); lifecycle.destroy(); web.destroy() }
+    }
+
+    @Test
+    @Config(shadows = [RecordingAudioMediaSession::class])
+    fun jpegArtworkReachesNotificationAndMediaDescription() {
+        // Real 16x16 JPEG generated by Chromium canvas, independent of Android bitmap shadows.
+        val artwork = "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gHYSUNDX1BST0ZJTEUAAQEAAAHIAAAAAAQwAABtbnRyUkdCIFhZWiAH4AABAAEAAAAAAABhY3NwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAA9tYAAQAAAADTLQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAlkZXNjAAAA8AAAACRyWFlaAAABFAAAABRnWFlaAAABKAAAABRiWFlaAAABPAAAABR3dHB0AAABUAAAABRyVFJDAAABZAAAAChnVFJDAAABZAAAAChiVFJDAAABZAAAAChjcHJ0AAABjAAAADxtbHVjAAAAAAAAAAEAAAAMZW5VUwAAAAgAAAAcAHMAUgBHAEJYWVogAAAAAAAAb6IAADj1AAADkFhZWiAAAAAAAABimQAAt4UAABjaWFlaIAAAAAAAACSgAAAPhAAAts9YWVogAAAAAAAA9tYAAQAAAADTLXBhcmEAAAAAAAQAAAACZmYAAPKnAAANWQAAE9AAAApbAAAAAAAAAABtbHVjAAAAAAAAAAEAAAAMZW5VUwAAACAAAAAcAEcAbwBvAGcAbABlACAASQBuAGMALgAgADIAMAAxADb/2wBDAAMCAgICAgMCAgIDAwMDBAYEBAQEBAgGBgUGCQgKCgkICQkKDA8MCgsOCwkJDRENDg8QEBEQCgwSExIQEw8QEBD/2wBDAQMDAwQDBAgEBAgQCwkLEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBD/wAARCAAQABADASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAn/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEBAAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AJVAA//Z"
+        assertNotNull(decodeArtwork(artwork))
+        val app = RuntimeEnvironment.getApplication()
+        val web = android.webkit.WebView(app); web.loadUrl("https://node.test/cloud")
+        val payload = state().put("session", "32345678-1234-1234-1234-123456789abc").put("artwork", artwork)
+        CompanionAudioBridge.receive(web, payload.toString(), "https://node.test", true, setOf("https://node.test")) {}
+        val lifecycle = Robolectric.buildService(CompanionAudioService::class.java).create()
+        try {
+            lifecycle.get().onStartCommand(null, 0, 1)
+            val notification = Shadows.shadowOf(lifecycle.get()).lastForegroundNotification
+            assertNotNull(notification.getLargeIcon())
+            // Robolectric's MediaController does not read MediaSession metadata;
+            // capture the actual service's setMetadata call instead.
+            val metadata = RecordingAudioMediaSession.metadata!!
+            assertNotNull(metadata.getBitmap(android.media.MediaMetadata.METADATA_KEY_ALBUM_ART))
+            assertNotNull(metadata.description.iconBitmap)
+            // Position-only refresh must retain the same thumbnail.
+            CompanionAudioBridge.receive(web, state().put("session", payload.getString("session")).put("sequence", 2).toString(),
+                "https://node.test", true, setOf("https://node.test")) {}
+            assertNotNull(Shadows.shadowOf(lifecycle.get()).lastForegroundNotification.getLargeIcon())
+            // A following song without art must not keep the previous cover.
+            CompanionAudioBridge.receive(web, state().put("session", payload.getString("session")).put("sequence", 3).put("artwork", "").toString(),
+                "https://node.test", true, setOf("https://node.test")) {}
+            assertNull(Shadows.shadowOf(lifecycle.get()).lastForegroundNotification.getLargeIcon())
+            assertNull(RecordingAudioMediaSession.metadata!!.description.iconBitmap)
+        } finally { CompanionAudioBridge.release(web); lifecycle.destroy(); web.destroy() }
+    }
+
+    @Test fun diagnosticReportExcludesPrivateMessagesAndRecordsRejectionStage() {
+        val app = RuntimeEnvironment.getApplication()
+        val web = android.webkit.WebView(app)
+        web.loadUrl("https://private-node.test/cloud?token=private-token")
+        try {
+            CompanionAudioBridge.receive(web, "private-invalid-payload", "https://private-node.test", true,
+                setOf("https://private-node.test")) {}
+            CompanionAudioBridge.receive(web, state().put("title", "PRIVATE SONG").put("duration", -1).toString(),
+                "https://private-node.test", true, setOf("https://private-node.test")) {}
+            val report = CompanionAudioDiagnostics.report(app)
+            assertTrue(report.contains("INVALID_JSON:"))
+            assertTrue(report.contains("INVALID_STATE:"))
+            for (privateValue in listOf("private-node", "private-token", "private-invalid-payload", "PRIVATE SONG", "12345678")) {
+                assertFalse(report.contains(privateValue))
+            }
+        } finally { web.destroy() }
+    }
+    @Test fun diagnosticHistoryIsBoundedWithoutDroppingStageCounts() {
+        repeat(100) {
+            CompanionAudioDiagnostics.record(CompanionAudioDiagnostics.Event.SERVICE_CREATED)
+            CompanionAudioDiagnostics.record(CompanionAudioDiagnostics.Event.SERVICE_DESTROYED)
+        }
+        val report = CompanionAudioDiagnostics.events()
+        val history = report.substringAfter("Recent transitions (seconds since boot):\n")
+        assertEquals(12, history.lines().count { it.isNotBlank() })
+        assertTrue(report.contains("SERVICE_CREATED:"))
+    }
+
+    private fun state() = JSONObject("""{"version":1,"action":"state","session":"12345678-1234-1234-1234-123456789abc","sequence":1,"title":"Current song","playing":true,"position":10,"duration":120,"previous":true,"next":true,"shuffle":true,"shuffled":false}""")
+    @Test fun malformedOrUnboundedMetadataCannotBecomeNativePlayback() {
+        for ((key, value) in listOf("version" to 2, "session" to "foreign", "sequence" to -1,
+                "position" to -1, "position" to 121, "duration" to 604801, "title" to "x".repeat(513),
+                "artwork" to "https://node.test/protected?token=secret")) {
+            assertTrue("Must reject $key", runCatching { CompanionAudioState.parse(state().put(key, value)) }.isFailure)
+        }
+    }
+    @Test fun currentMetadataPreservesPauseSeekAndQueueCapabilities() {
+        val parsed = CompanionAudioState.parse(state().put("playing", false).put("shuffled", true))
+        assertFalse(parsed.playing); assertTrue(parsed.shuffled)
+        assertTrue(parsed.previous && parsed.next && parsed.shuffle)
+        assertEquals(10.0, parsed.position, 0.0)
+        assertEquals(120.0, parsed.duration, 0.0)
+        assertEquals("", parsed.artwork)
+    }
+    @Test fun artworkNeverFetchesProtectedUrlsAndRejectsInvalidBytes() {
+        assertNull(decodeArtwork("https://node.test/protected"))
+        assertNull(decodeArtwork("data:image/jpeg;base64,AAAA"))
+        assertNull(decodeArtwork("data:image/jpeg;base64," + "A".repeat(90000)))
+    }
+    @Test fun serviceRestartWithoutLiveAuthorizedSessionDoesNotResumePlayback() {
+        val lifecycle = Robolectric.buildService(CompanionAudioService::class.java).create()
+        try {
+            assertEquals(android.app.Service.START_NOT_STICKY, lifecycle.get().onStartCommand(null, 0, 1))
+            assertNull(CompanionAudioBridge.state)
+            assertNull(CompanionAudioService.instance)
+        } finally { lifecycle.destroy() }
+    }
+}
+
+@org.robolectric.annotation.Implements(android.media.session.MediaSession::class)
+class RecordingAudioMediaSession : org.robolectric.shadows.ShadowMediaSession() {
+    companion object { var metadata: android.media.MediaMetadata? = null }
+    @org.robolectric.annotation.Implementation
+    fun setMetadata(value: android.media.MediaMetadata) { metadata = value }
+}

Android/app/src/test/java/com/archipelago/app/ui/screens/WebViewDownloadsTest.kt

@@ -0,0 +1,88 @@
+package com.archipelago.app.ui.screens
+
+import okhttp3.OkHttpClient
+import okhttp3.ResponseBody.Companion.toResponseBody
+import okhttp3.mockwebserver.MockResponse
+import okhttp3.mockwebserver.MockWebServer
+import okio.Buffer
+import org.junit.Assert.*
+import org.junit.Test
+import java.io.ByteArrayOutputStream
+import java.io.IOException
+import java.util.concurrent.CancellationException
+
+class WebViewDownloadsTest {
+    private fun spec(url: String) = WebDownload(url, "test-agent", "session=test-only", "file.bin", "application/octet-stream")
+    @Test fun authenticatedDownloadWritesExactBytesAndReportsCompletion() {
+        MockWebServer().use { server ->
+            val bytes = ByteArray(256 * 1024 + 13) { (it % 251).toByte() }
+            server.enqueue(MockResponse().setBody(Buffer().write(bytes)))
+            val out = ByteArrayOutputStream()
+            var progress = 0L to 0L
+            assertEquals(bytes.size.toLong(), streamWebDownload(spec(server.url("/file").toString()), out, OkHttpClient(), onProgress = { done, total -> progress = done to total }))
+            assertArrayEquals(bytes, out.toByteArray())
+            assertEquals(bytes.size.toLong() to bytes.size.toLong(), progress)
+            assertEquals("session=test-only", server.takeRequest().getHeader("Cookie"))
+        }
+    }
+    @Test fun sameOriginRedirectKeepsSessionButCrossOriginNeverReceivesIt() {
+        MockWebServer().use { first -> MockWebServer().use { second ->
+            second.enqueue(MockResponse().setBody("final"))
+            first.enqueue(MockResponse().setResponseCode(302).addHeader("Location", "/relative"))
+            first.enqueue(MockResponse().setResponseCode(307).addHeader("Location", second.url("/target")))
+            val out = ByteArrayOutputStream()
+            streamWebDownload(spec(first.url("/start").toString()), out, OkHttpClient())
+            assertEquals("final", out.toString())
+            assertEquals("session=test-only", first.takeRequest().getHeader("Cookie"))
+            assertEquals("session=test-only", first.takeRequest().getHeader("Cookie"))
+            assertNull(second.takeRequest().getHeader("Cookie"))
+        } }
+    }
+    @Test fun authenticationFailureDoesNotSaveErrorBody() {
+        MockWebServer().use { server ->
+            server.enqueue(MockResponse().setResponseCode(401).setBody("login required"))
+            val out = ByteArrayOutputStream()
+            val error = assertThrows(IOException::class.java) { streamWebDownload(spec(server.url("/").toString()), out, OkHttpClient()) }
+            assertTrue(error.message!!.startsWith("Sign in"))
+            assertEquals(0, out.size())
+        }
+    }
+    @Test fun redirectsAreBoundedAndUnsafeSchemesAreRejected() {
+        MockWebServer().use { server ->
+            repeat(6) { server.enqueue(MockResponse().setResponseCode(302).addHeader("Location", "/loop")) }
+            assertThrows(IOException::class.java) { streamWebDownload(spec(server.url("/loop").toString()), ByteArrayOutputStream(), OkHttpClient()) }
+            assertEquals(6, server.requestCount)
+        }
+        for (url in listOf("file:///etc/passwd", "data:text/plain,test", "blob:test")) {
+            assertThrows(IOException::class.java) { streamWebDownload(spec(url), ByteArrayOutputStream(), OkHttpClient()) }
+        }
+    }
+    @Test fun cancellationAndDestinationFailureAreNotReportedAsComplete() {
+        MockWebServer().use { server ->
+            server.enqueue(MockResponse().setBody("bytes"))
+            assertThrows(CancellationException::class.java) { streamWebDownload(spec(server.url("/").toString()), ByteArrayOutputStream(), OkHttpClient(), checkCancelled = { throw CancellationException() }) }
+            assertEquals(0, server.requestCount)
+            var progressCalled = false
+            val out = object : java.io.OutputStream() { override fun write(b: Int) { throw IOException("disk full") } }
+            assertThrows(IOException::class.java) { streamWebDownload(spec(server.url("/").toString()), out, OkHttpClient(), onProgress = { _, _ -> progressCalled = true }) }
+            assertFalse(progressCalled)
+        }
+    }
+    @Test fun tlsDowngradeAndLoginHtmlAreRejected() {
+        var requests = 0
+        val client = OkHttpClient.Builder().addInterceptor { chain ->
+            requests++
+            okhttp3.Response.Builder().request(chain.request()).protocol(okhttp3.Protocol.HTTP_1_1)
+                .code(302).message("redirect").header("Location", "http://example.test/file").body("".toResponseBody(null)).build()
+        }.build()
+        assertThrows(IOException::class.java) { streamWebDownload(spec("https://example.test/file"), ByteArrayOutputStream(), client) }
+        assertEquals(1, requests)
+        MockWebServer().use { server ->
+            server.enqueue(MockResponse().addHeader("Content-Type", "Text/HTML; charset=utf-8").setBody("<html>Sign in</html>"))
+            val out = ByteArrayOutputStream()
+            assertThrows(IOException::class.java) { streamWebDownload(spec(server.url("/file").toString()), out, OkHttpClient()) }
+            assertEquals(0, out.size())
+        }
+    }
+
+}

Android/app/src/test/java/com/archipelago/app/ui/screens/WebViewFullscreenTest.kt

@@ -0,0 +1,90 @@
+package com.archipelago.app.ui.screens
+
+import android.view.View
+import android.widget.FrameLayout
+import androidx.activity.ComponentActivity
+import org.junit.Assert.*
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.Robolectric
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+@RunWith(RobolectricTestRunner::class)
+@Config(manifest = Config.NONE, sdk = [28, 35])
+class WebViewFullscreenTest {
+    @Test fun closingVideoInPipKeepsOpaqueCoverUntilActivityReturns() {
+        val lifecycle = Robolectric.buildActivity(ComponentActivity::class.java).setup()
+        try {
+            val activity = lifecycle.get()
+            val fullscreen = WebViewFullscreen(activity)
+            val video = View(activity)
+            var hidden = 0
+            fullscreen.show(video) { hidden++ }
+            assertTrue(activity.enterPictureInPictureMode(android.app.PictureInPictureParams.Builder().build()))
+            assertTrue(activity.isInPictureInPictureMode)
+            fullscreen.hide()
+            assertNull(video.parent)
+            assertTrue(fullscreen.isActive)
+            assertEquals(1, hidden)
+            fullscreen.hide()
+            assertEquals(1, hidden)
+        } finally { lifecycle.pause().stop().destroy() }
+    }
+
+    @Test fun backExitsFullscreenWithoutFinishingActivityAndNotifiesOnce() {
+        val lifecycle = Robolectric.buildActivity(ComponentActivity::class.java).setup()
+        try {
+            val activity = lifecycle.get()
+            val fullscreen = WebViewFullscreen(activity)
+            val video = View(activity)
+            var hidden = 0
+            fullscreen.show(video) { hidden++ }
+            assertNotNull(video.parent)
+            activity.onBackPressedDispatcher.onBackPressed()
+            assertNull(video.parent)
+            assertFalse(activity.isFinishing)
+            assertEquals(1, hidden)
+            fullscreen.hide()
+            assertEquals(1, hidden)
+        } finally { lifecycle.pause().stop().destroy() }
+    }
+
+    @Test fun duplicateRequestPreservesActiveViewAndCanReenterAfterExit() {
+        val lifecycle = Robolectric.buildActivity(ComponentActivity::class.java).setup()
+        try {
+            val activity = lifecycle.get()
+            val fullscreen = WebViewFullscreen(activity)
+            val first = View(activity)
+            val second = View(activity)
+            var firstHidden = 0
+            var secondHidden = 0
+            fullscreen.show(first) { firstHidden++ }
+            fullscreen.show(second) { secondHidden++ }
+            assertNotNull(first.parent)
+            assertNull(second.parent)
+            assertEquals(0, firstHidden)
+            assertEquals(1, secondHidden)
+            fullscreen.hide()
+            fullscreen.show(second) { secondHidden++ }
+            assertNotNull(second.parent)
+            fullscreen.hide()
+            assertEquals(1, firstHidden)
+            assertEquals(2, secondHidden)
+        } finally { lifecycle.pause().stop().destroy() }
+    }
+
+    @Test fun rejectsOwnedViewWithoutReparentingAndHandlesUnavailableActivity() {
+        val lifecycle = Robolectric.buildActivity(ComponentActivity::class.java).setup()
+        try {
+            val activity = lifecycle.get()
+            val video = View(activity)
+            val owner = FrameLayout(activity).apply { addView(video) }
+            var hidden = 0
+            WebViewFullscreen(activity).show(video) { hidden++ }
+            assertSame(owner, video.parent)
+            WebViewFullscreen(null).show(null) { hidden++ }
+            assertEquals(2, hidden)
+        } finally { lifecycle.pause().stop().destroy() }
+    }
+}

CHANGELOG.md

@@ -1,6 +1,116 @@
 # Changelog
 
-## Unreleased
+## v1.9.0-alpha (2026-10-05)
+
+Unpublished release candidate; qualification is still in progress.
+
+- Keep Cuprate and NetBird supporting components out of app listings and consolidate BTCPay Server under Commerce.
+- Default on-chain sends, channel opens and cooperative closes to a dynamic next-block fee target, preserving explicit slower and custom choices.
+- Add reviewed fee-bump quotes, explicit budgets and durable operation tracking for supported wallet transactions.
+- Preserve Nginx Proxy Manager storage, same-node upstream connectivity, certificates and access controls through managed migrations.
+- Restrict public management access while retaining configured public apps and ACME certificate validation.
+- Serve the Mempool explorer on the Angor indexer origin alongside its API.
+- Include the self-contained LoRa flashing tool and explicit board selection in update and installer payloads.
+- Preserve paid-file Lightning entitlements across restarts and recover settled invoices from LND. Retry delivery without paying again and retain purchased files in the owned cache.
+- Return explicit payment-status errors with safe retry guidance when verification is unavailable.
+- Keep upload progress on its original screen, show completion there or notify on other screens, and cancel active and queued uploads.
+- Resume interrupted uploads while the app remains open, preserve the original destination, and verify saved file contents before reporting completion.
+- Provision a unique private File Browser login on each node while keeping Cloud sign-in automatic and preserving existing accounts and files.
+- Update Nostr dependencies to reject forged relay events and oversized encrypted messages; preserve native signing and encryption compatibility.
+- Allow apps to opt in to a validated public-key list of user identities without granting signing access.
+- Make transaction filters transparent and horizontally scrollable on mobile.
+- Keep Immich internal services out of My Apps, avoid false recovery states for healthy stacks, and allow removal of retired catalog apps.
+- Repair the redundant managed Portainer network override that can prevent startup, preserving custom overrides and persistent state.
+- Offer Standard, Medium, Fast and custom fees when cooperatively closing Lightning channels.
+- Add a clear-search icon to My Apps, Services and the App Store on desktop and mobile.
+- Keep Angor Indexer and the optional Angor Relay in the signed app catalog. Full indexing requires a synced, unpruned Bitcoin node and its indexing dependencies.
+
+## v1.8.22-alpha (2026-09-30)
+
+- Fixed Nginx Proxy Manager launch readiness choosing a proxy listener instead of its admin port after container recreation.
+
+- Network diagnostic failures no longer stop all apps or rebuild shared container networking.
+- Prevented orphaned companion dashboards from repeatedly reinstalling themselves after their backend app was removed.
+- Fixed companion dashboard builds still referencing a retired image registry.
+
+- Fixed Angor Indexer health checks choosing IPv6 localhost for an IPv4 listener and unnecessarily restarting the working service.
+
+- Prevented false app restarts by probing each published port at its actual bind address; Nginx Proxy Manager now checks its internal admin API.
+- Added a backed-up migration for the recognized legacy Nginx Proxy Manager tunnel/LND port conflict in both OTA and ISO startup paths.
+
+- Checked Bitcoin and Electrum companion dashboards instead of backend protocol ports, preserving dashboard access during initial sync.
+- Removed web-interface waiting messages from headless services such as Phoenixd and clarified which interface is unavailable for launchable apps.
+
+- Finished runtime app-file promotion before manifest loading, preventing startup catalog refresh from forgetting disk-only apps.
+
+- Named the app in compact readiness messages and kept app-card actions aligned at the bottom.
+- Removed duplicate Mempool cards caused by frontend container aliases in restored inventory.
+
+- Kept installed apps visible through restarts and hard refreshes, and delayed app launches until their web interface is ready.
+- Made Bitcoin version selection readable and usable in the ThinkPad kiosk, above the pruning settings.
+- Restored GitWorkshop build files in installation/update payloads and made slow image-pull progress clearer.
+- Fixed same-node Gitea access from Portainer, with persistent runtime migration, state backups and recovery after failed restarts.
+- Preserved Gitea configuration and SSH operation during fresh setup and upgrades.
+- Improved paid-file delivery, saved-file permissions and repeat-download compatibility; verified Tor-only payment with change, rejection refunds and free repeat downloads.
+- Added a headless Angor Indexer service using the existing Mempool/ElectrumX stack, and an optional separate Angor relay.
+- Prevented manifest command arguments containing apostrophes from being corrupted in generated services.
+
+## v1.8.21-alpha (2026-09-30)
+
+- Fixed Bitcoin and other containers being forcibly stopped after ten seconds during managed updates and restarts.
+- Existing installations now receive the same graceful shutdown allowance as new containers, without restarting apps just to apply this setting.
+- Prevented unnecessary Lightning restarts when Bitcoin has stayed running; dependency restarts now require an observed Bitcoin container change.
+- Includes the Cashu payment, optional Bitcoin pruning, Lightning readiness, and explorer improvements from 1.8.20.
+
+## v1.8.20-alpha (2026-09-29)
+
+- Fixed Cashu file payments rejected despite a shared mint, and preserved the payment amount when mint fees reduce change.
+- Payment failures now report whether a refund actually succeeded; missing files and unsupported payment methods are rejected before charging.
+- Improved saving paid files into Files and reopening purchases without paying again.
+- Bitcoin Core and Knots installation offers optional pruning on larger disks, using the same settings as automatic pruning.
+- Fixed false missing-port checks that unnecessarily restarted Bitcoin and LND; recovery now respects managed shutdown timeouts.
+- LND explains when it is waiting for Bitcoin installation, startup, or sync, without treating normal synchronization as a restart-worthy failure.
+- Bitcoin startup messages explain block-index loading without exposing raw RPC errors, and Lightning keeps known balances clearly marked during outages.
+- Changed the public transaction-explorer default to mempool.space while preserving local explorers and custom choices.
+
+## v1.8.19-alpha (2026-09-28)
+
+- Fixed the embedded AIUI chat page painting a second background and dark scrim over Archy’s dashboard background.
+- Embedded AIUI now stays transparent so the dashboard background appears once.
+- AIUI background fixes are now included reliably in OTA updates and fresh installations.
+
+## v1.8.18-alpha (2026-09-18)
+
+- Framework startup prioritizes Bitcoin and LND before unrelated containers, and unavailable LND balances remain unavailable instead of appearing as false zeroes.
+- Cashu Receive guides unseeded wallets through recovery-phrase setup, with shorter backup guidance and a single-column layout.
+- Added live Framework verification for automatic LND unlock, native balance preservation, Cashu address registration, and proof preservation.
+
+## v1.8.17-alpha (2026-09-15)
+
+- Minibits claims that every mint reports as already spent leave the retry queue, clearing repeated failure notices. Network errors and mixed mint failures remain queued for another attempt.
+- Minibits polls its primary relay first and connects to public fallback relays only when the primary is unreachable, reducing unnecessary connections.
+- Large payment backlogs are fetched from newest to oldest with a saved cursor, so polling can resume after interruptions or page limits. Payments sharing the same timestamp remain reachable.
+- Added regression coverage for spent-claim classification, wrapped and mixed mint errors, same-second payments, and interrupted or multi-poll backlogs.
+
+## v1.8.16-alpha (2026-09-15)
+
+- App updates refresh and verify the signed catalog before changing containers. A failed refresh or manifest reload cancels the update, and automatic updates wait for a successful refresh.
+- Fixed repeated Mempool update offers: downstream `-archyN` patches now sort above their upstream release, and moving a published image between registry namespaces does not hide a genuine upgrade.
+- Updates inspect installed component versions, refuse known downgrades, skip containers already at the target versions, and verify the resulting versions before reporting success.
+- Added regression coverage for stale catalogs, matching versions, publisher namespace changes, stack component updates, and keeping running containers untouched when no upgrade is needed.
+
+## v1.8.15-alpha (2026-09-13)
+
+- Cuprate is presented as one user-facing app in My Apps, including its UI launch button; the generated dashboard companion is hidden as an implementation detail instead of appearing under Services.
+- Added regression coverage for Cuprate install and installed-state grouping.
+- Release validation was rerun on the corrected tree before OTA and ISO publication.
+
+## v1.8.14-alpha (2026-09-13)
+
+- **Cuprate gains a first-party companion dashboard.** The Monero node now has a Bitcoin-style status UI, safe app grouping, a 450 GB disk-safety gate, and a restricted RPC that is never exposed as a launch page.
+- **Bitcoin Core Tor enrollment uses the correct protocol identity.** `bitcoin-core` is forwarded on port 8333 and resolves to its own hidden-service directory without disturbing legacy Bitcoin aliases.
+- **GitWorkshop opens Archipelago’s canonical ngit repository by default.** The launcher and registry promotion use the full maintainer/relay/`archy` coordinate, with regression coverage for Companion and browser-tab launches.
+- **Release validation is stricter.** The registry gate now checks the complete canonical source deep link, and the merged candidate passed the full frontend and focused backend test suites.
 
 ## v1.8.13-alpha (2026-09-12)
 

CONTRIBUTING.md

@@ -64,12 +64,49 @@ App submissions must:
 
 ## Pull requests
 
-1. Open one focused PR per behavior or documentation change.
+Contributions, PRs and reviews live on **ngit**. Clone the canonical repository:
+
+```text
+nostr://npub1w3sqdkrhn0gyuvsex32effzgnfpyde6qrrc4u467flg5e9txh4wsfn5vjg/relay.ngit.dev/archy
+```
+
+Gitea is a conventional Git mirror of accepted `main` commits and release tags.
+You do not need to open a duplicate Gitea PR. Existing Gitea contributions will
+be reviewed and linked to their ngit replacement or accepted result before
+closure.
+
+1. Open one focused ngit PR per behavior or documentation change.
 2. Explain what changed, why it changed, and how it was verified.
 3. Include screenshots for UI changes.
 4. Link relevant issues or docs.
 5. Keep generated catalog changes in sync with manifest changes.
 
+### Maintainer publication gate
+
+Merge once through the ngit contribution workflow, then push the exact same
+accepted commits to Gitea. Do not independently merge or squash on each mirror.
+Publish identical release tag objects, including annotations and signatures.
+After pushing main, verify:
+
+```bash
+python3 scripts/check-git-mirrors.py --local
+```
+
+Before publishing release artifacts, also check the actual release tag:
+
+```bash
+python3 scripts/check-git-mirrors.py --local --ref refs/tags/v1.9.0-alpha
+```
+
+Use the release's actual tag name. Missing refs, inaccessible mirrors or differing
+object IDs block publication. Record the ngit PR disposition and resulting merge
+commit in the release acceptance ledger. Resolve drift deliberately; do not
+force-push or delete published history without explicit approval.
+
+The checker is read-only. `--all` audits every advertised branch and tag; ngit
+proposal branches may intentionally differ from Gitea. A main-only pass proves
+only main parity, and no Git ref check verifies PR discussions or review state.
+
 Suggested commit format:
 
 ```text

README.md

@@ -1,5 +1,7 @@
 # Archipelago
 
+> **Alpha testing:** Archipelago is experimental software. Any funds you put on it are at your own risk.
+
 > Self-sovereign Bitcoin node OS and manifest-driven app platform.
 
 Archipelago is a bootable personal server OS for Bitcoin infrastructure,

aiui/packages/app/server/dev-auth.ts

@@ -46,13 +46,14 @@ interface RateBucket {
 
 const rateBuckets = new Map<string, RateBucket>()
 
-// Clean up stale buckets every 5 minutes
+// Vite imports this module during builds too; cleanup must not keep the
+// process alive once compilation has finished.
 setInterval(() => {
   const now = Date.now()
   for (const [key, bucket] of rateBuckets) {
     if (now > bucket.resetAt) rateBuckets.delete(key)
   }
-}, 5 * 60_000)
+}, 5 * 60_000).unref()
 
 function getClientIp(req: IncomingMessage): string {
   return req.socket.remoteAddress ?? 'unknown'

aiui/packages/app/src/__tests__/providerBridge.test.ts

@@ -0,0 +1,28 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { archyBridge } from '@/services/archyBridge'
+const originalParent = window.parent
+const origin = 'https://node.example'
+afterEach(() => { archyBridge.destroy(); Object.defineProperty(window, 'parent', { value: originalParent, configurable: true }); vi.restoreAllMocks() })
+describe('trusted provider setup bridge', () => {
+  it('accepts configuration only from the embedding parent, rejects siblings and other origins', () => {
+    const parent = { postMessage: vi.fn() }
+    Object.defineProperty(window, 'parent', { value: parent, configurable: true })
+    archyBridge.init(origin)
+    const listener = vi.fn(); const unsubscribe = archyBridge.onProviderConfigured(listener)
+    const send = (source: unknown, from: string, provider = 'openai') => window.dispatchEvent(new MessageEvent('message', { source: source as Window, origin: from, data: { type: 'ai:provider-configured', provider, model: 'test-model' } }))
+    send({}, origin); send(parent, 'https://evil.example'); send(parent, origin, 'arbitrary')
+    expect(listener).not.toHaveBeenCalled()
+    send(parent, origin)
+    expect(listener).toHaveBeenCalledExactlyOnceWith({ provider: 'openai', model: 'test-model' })
+    archyBridge.requestAISetup()
+    expect(parent.postMessage).toHaveBeenLastCalledWith({ type: 'ai:setup-request' }, origin)
+    unsubscribe()
+  })
+  it('replays the selection when the composer mounts after the handshake', () => {
+    const parent = { postMessage: vi.fn() }; Object.defineProperty(window, 'parent', { value: parent, configurable: true })
+    archyBridge.init(origin)
+    window.dispatchEvent(new MessageEvent('message', { source: parent as unknown as Window, origin, data: { type: 'ai:provider-configured', provider: 'local' } }))
+    const listener = vi.fn(); const unsubscribe = archyBridge.onProviderConfigured(listener)
+    expect(listener).toHaveBeenCalledExactlyOnceWith({ provider: 'local', model: '' }); unsubscribe()
+  })
+})

aiui/packages/app/src/__tests__/useAI.test.ts

@@ -249,6 +249,24 @@ describe('useAI', () => {
       expect(chatStore.isStreaming).toBe(false)
     })
 
+    it.each([502, 503, 429, 401])('distinguishes HTTP %s from a missing credential', async (status) => {
+      globalThis.fetch = vi.fn().mockResolvedValue({ ok: false, status, text: async () => 'Provider request failed' })
+      const store = useChatStore(); store.webSearchEnabled = false
+      const ai = useAI(); ai.needsApiKey.value = false
+      await ai.sendMessage('test')
+      expect(ai.needsApiKey.value).toBe(status === 401)
+      expect(store.isStreaming).toBe(false)
+    })
+
+    it('offers funding for a Routstr payment-required response without mislabeling it a key error', async () => {
+      globalThis.fetch = vi.fn().mockResolvedValue({ ok: false, status: 402, text: async () => JSON.stringify({ error: { message: 'Your spending allowance is exhausted' } }) })
+      const store = useChatStore(); store.webSearchEnabled = false
+      const ai = useAI(); ai.setProvider('routstr'); ai.needsApiKey.value = false; ai.needsFunding.value = false
+      await ai.sendMessage('test')
+      expect(ai.needsFunding.value).toBe(true); expect(ai.needsApiKey.value).toBe(false)
+      expect(store.messages.find(m => m.role === 'assistant')?.content).toContain('spending allowance')
+    })
+
     it('handles connection errors gracefully', async () => {
       globalThis.fetch = vi.fn().mockRejectedValue(new Error('Network failure'))
 

aiui/packages/app/src/components/chat/ChatHeader.vue

@@ -123,6 +123,7 @@
           :style="modelPickerDropdownStyle"
           @click.stop
         >
+        <button v-if="archyBridge.isInArchy()" class="w-full text-left rounded-lg px-3 py-2 text-sm text-white/90 hover:bg-white/10" @click="showModelPicker = false; archyBridge.requestAISetup()">AI connection</button>
         <div v-for="provider in availableProviders" :key="provider.id">
           <p class="text-xs font-semibold uppercase tracking-wider mb-1.5 px-1 text-white/40">
             {{ provider.name }}
@@ -247,6 +248,7 @@ import { useAI } from '@/composables/useAI'
 import { useContentPanel } from '@/composables/useContentPanel'
 import { downloadConversation, type ExportFormat } from '@/utils/conversation-export'
 import { parseImportFile } from '@/utils/conversation-import'
+import { archyBridge } from '@/services/archyBridge'
 import { useComparisonMode } from '@/composables/useComparisonMode'
 
 defineProps<{
@@ -332,8 +334,7 @@ const modelDisplayName = computed(() => {
 })
 
 function selectModel(providerId: string, modelId: string) {
-  setProvider(providerId as 'routstr' | 'claude' | 'openrouter' | 'mock')
-  setModel(modelId)
+  if (setProvider(providerId as Parameters<typeof setProvider>[0])) setModel(modelId)
   showModelPicker.value = false
 }
 

aiui/packages/app/src/components/chat/ChatWindow.vue

@@ -186,8 +186,9 @@ defineEmits<{
 }>()
 
 const chatStore = useChatStore()
-const { sendMessage, stopGeneration, editAndResend, regenerateLastResponse, activeModel, needsApiKey } = useAI()
+const { sendMessage, stopGeneration, editAndResend, regenerateLastResponse, activeModel, needsApiKey, needsFunding } = useAI()
 const { updatePanelFromText, panelOpen, panelFilms, panelTitle, activeTab, availableTabs, setActiveTab, enterDesignSystemMode } = useContentPanel()
+import { archyBridge } from '@/services/archyBridge'
 import { useCodeContext } from '@/composables/useCodeContext'
 import { useVisualViewport } from '@/composables/useVisualViewport'
 const codeContext = useCodeContext()
@@ -206,11 +207,19 @@ const showSettings = ref(false)
 // without fixing anything).
 watch(needsApiKey, (needs) => {
   if (needs) {
-    showSettings.value = true
+    if (archyBridge.isInArchy()) archyBridge.requestAISetup()
+    else showSettings.value = true
     needsApiKey.value = false
   }
 })
 
+watch(needsFunding, needed => {
+  if (!needed) return
+  if (archyBridge.isInArchy()) archyBridge.requestAISetup('funding')
+  else showSettings.value = true
+  needsFunding.value = false
+})
+
 // Scroll position memory per conversation
 const scrollPositions = new Map<string, number>()
 

aiui/packages/app/src/components/settings/ApiKeyManager.vue

@@ -1,5 +1,9 @@
 <template>
-  <div class="space-y-4">
+  <div v-if="embedded" class="space-y-3">
+    <p class="text-sm">AI connections and private keys are managed by this node.</p>
+    <button class="rounded-lg px-3 py-2 bg-white/10 text-sm" @click="archyBridge.requestAISetup()">Manage AI connection</button>
+  </div>
+  <div v-else class="space-y-4">
     <h3 class="text-sm font-bold" :class="isDark ? 'text-white/90' : 'text-gray-900'">
       API Keys
     </h3>
@@ -93,10 +97,12 @@
 </template>
 
 <script setup lang="ts">
+import { archyBridge } from '@/services/archyBridge'
 import { ref, onMounted } from 'vue'
 import { useTheme } from '@/composables/useTheme'
 import { storeApiKey, getApiKey, deleteApiKey, listProviders, maskApiKey } from '@/utils/key-vault'
 
+const embedded = archyBridge.isInArchy()
 const { isDark } = useTheme()
 
 interface ProviderInfo {
@@ -156,5 +162,5 @@ async function removeKey(provider: string) {
   await loadProviders()
 }
 
-onMounted(loadProviders)
+onMounted(() => { if (!embedded) void loadProviders() })
 </script>

aiui/packages/app/src/composables/useAI.ts

@@ -13,7 +13,7 @@ import { useCodeContext } from '@/composables/useCodeContext'
 import { apiFetch } from '@/utils/api-fetch'
 import { useSettingsStore } from '@/stores/settings'
 
-type Provider = 'routstr' | 'claude' | 'openrouter' | 'mock'
+type Provider = 'routstr' | 'claude' | 'openrouter' | 'mock' | 'openai' | 'auto' | 'local'
 
 // API paths are relative to the base URL so they work both in dev (/) and Archy (/aiui/)
 const BASE = import.meta.env.BASE_URL || '/'
@@ -120,34 +120,15 @@ Prioritize Podcasting 2.0–friendly platforms: Fountain.fm, Podcast Index, Cast
 Always include these tags so the UI can render rich cards. Write a brief reason why each is worth checking out.
 ${librarySection}`
 
-const activeProvider = ref<Provider>('claude')
+const activeProvider = ref<Provider>(archyBridge.isInArchy() ? 'auto' : 'claude')
 
 const activeModel = ref('claude-haiku-4.5')
 
-// One-shot signal a send/regenerate/edit failure looked like a missing or
-// invalid API key (or an unreachable proxy) rather than a transient/server
-// error — consumed by ChatWindow.vue to auto-open Settings so the user isn't
-// left in a dead end with no obvious next step. Deliberately narrow (401/403,
-// explicit "api key"/"unauthorized" text, or a connection-level failure to
-// reach the proxy at all) so a rate-limited or momentarily-flaky provider
-// response does NOT send the user to Settings for a problem Settings can't
-// fix. Reset to false by the consumer immediately after acting on it, so it
-// behaves as a pulse rather than sticky state (each new failure can re-fire).
+// Credentials require setup; network failures and provider outages require retry.
 const needsApiKey = ref(false)
-
+const needsFunding = ref(false)
 function looksLikeMissingApiKey(err: string): boolean {
-  const lower = err.toLowerCase()
-  return (
-    /\b(401|403)\b/.test(err) ||
-    lower.includes('api key') ||
-    lower.includes('x-api-key') ||
-    lower.includes('unauthorized') ||
-    lower.includes('authentication_error') ||
-    lower.includes('failed to fetch') ||
-    lower.includes('econnrefused') ||
-    lower.includes(' 502') ||
-    lower.includes(' 503')
-  )
+  return /\b(401|403)\b|api[ _-]?key|unauthorized|authentication_error|credential/i.test(err)
 }
 
 // ─── Routstr model catalog (fetched from the node's session-gated proxy) ───
@@ -161,7 +142,7 @@ async function refreshRoutstrModels() {
   routstrModelsFetched = true
   try {
     const res = await apiFetch(ROUTSTR_MODELS_PATH)
-    if (!res.ok) return
+    if (!res.ok) { routstrModelsFetched = false; return }
     const data = await res.json()
     if (Array.isArray(data?.data)) {
       routstrModels.value = data.data
@@ -170,13 +151,21 @@ async function refreshRoutstrModels() {
           id: m.id as string,
           name: (m.name as string) || (m.id as string),
         }))
-    }
+      if (activeProvider.value === 'routstr' && activeModel.value === 'routstr-unavailable' && routstrModels.value[0]) activeModel.value = routstrModels.value[0].id
+    } else { routstrModelsFetched = false }
   } catch {
     routstrModelsFetched = false // allow a retry on the next send/open
   }
 }
 
 const availableProviders = computed(() => {
+  if (archyBridge.isInArchy()) return [
+    { id: 'local' as Provider, name: 'Local AI', models: [{ id: 'node', name: 'Node configuration' }] },
+    { id: 'auto' as Provider, name: 'Node AI', models: [{ id: 'node', name: 'Node configuration' }] },
+    { id: 'claude' as Provider, name: 'Claude API', models: [{ id: 'node', name: 'Node configuration' }] },
+    { id: 'openai' as Provider, name: 'OpenAI API', models: [{ id: activeProvider.value === 'openai' ? activeModel.value : 'node', name: activeProvider.value === 'openai' ? activeModel.value : 'Configure model' }] },
+    { id: 'routstr' as Provider, name: 'Routstr (sats)', models: routstrModels.value.length ? routstrModels.value : [{ id: 'routstr-unavailable', name: 'Models unavailable — retry' }] },
+  ]
   const providers: { id: Provider; name: string; models: { id: string; name: string }[] }[] = [
     {
       id: 'routstr',
@@ -187,7 +176,7 @@ const availableProviders = computed(() => {
     },
     {
       id: 'claude',
-      name: 'Claude (Max)',
+      name: 'Claude API',
       models: [
         { id: 'claude-haiku-4.5', name: 'Claude 4.5 Haiku' },
         { id: 'claude-sonnet-4', name: 'Claude Sonnet 4' },
@@ -207,24 +196,36 @@ const availableProviders = computed(() => {
   })
   providers.push({
     id: 'mock',
-    name: 'Local (no API)',
+    name: 'Demo echo',
     models: [{ id: 'echo', name: 'Echo (mirror input)' }],
   })
   return providers
 })
 
 function setProvider(provider: Provider) {
+  if (archyBridge.isInArchy()) {
+    if (provider === 'routstr' && activeProvider.value === 'routstr') return true
+    archyBridge.requestAISetup(); return false
+  }
   activeProvider.value = provider
   const p = availableProviders.value.find((pp) => pp.id === provider)
   if (p && p.models.length > 0) {
     activeModel.value = p.models[0].id
   }
+  return true
 }
 
 function setModel(model: string) {
+  if (archyBridge.isInArchy() && activeProvider.value !== 'routstr') { archyBridge.requestAISetup(); return }
   activeModel.value = model
 }
 
+archyBridge.onProviderConfigured(({ provider, model }) => {
+  activeProvider.value = provider
+  activeModel.value = model || (provider === 'routstr' ? routstrModels.value[0]?.id || 'routstr-unavailable' : 'node')
+  if (provider === 'routstr') void refreshRoutstrModels()
+})
+
 interface ChatMessage {
   role: 'user' | 'assistant'
   content: string
@@ -448,6 +449,7 @@ async function streamRoutstr(
   })
 
   const bodyText = await res.text().catch(() => '')
+  if (res.status === 402) needsFunding.value = true
   if (!res.ok) {
     // The node's refusals carry a plain-language error.message (budget not
     // set, budget spent, wallet can't fund) — surface it verbatim.
@@ -974,5 +976,6 @@ export function useAI() {
     setProvider,
     setModel,
     needsApiKey,
+    needsFunding,
   }
 }

aiui/packages/app/src/main.ts

@@ -33,6 +33,7 @@ const PWA_CACHE_VERSION = '2'
 // Only embedded when explicitly requested via ?embedded param
 const _embeddedFlag = new URLSearchParams(window.location.search).has('embedded')
 ;(window as unknown as Record<string, unknown>).__AIUI_EMBEDDED__ = _embeddedFlag
+document.documentElement.classList.toggle('aiui-embedded', _embeddedFlag)
 
 const router = createRouter({
   history: createWebHistory(import.meta.env.BASE_URL),

aiui/packages/app/src/pages/ChatPage.vue

@@ -2,13 +2,13 @@
   <div
     class="h-full flex flex-col relative overflow-hidden transition-colors duration-300"
     :class="[]"
-    :style="isDark
-      ? { background: '#000 url(' + bgImageUrl + ') center center / cover no-repeat fixed' }
-      : isEmbedded
+    :style="isEmbedded
       ? { background: 'transparent' }
+      : isDark
+        ? { background: '#000 url(' + bgImageUrl + ') center center / cover no-repeat fixed' }
         : { backgroundColor: '#f5f4f1' }"
   >
-    <div v-if="isDark" class="absolute inset-0 pointer-events-none bg-black/20" />
+    <div v-if="isDark && !isEmbedded" class="absolute inset-0 pointer-events-none bg-black/20" />
 
     <!-- Desktop layout -->
     <div

aiui/packages/app/src/services/archyBridge.ts

@@ -55,6 +55,10 @@ interface ThemeInfo {
 type PermissionsCallback = (categories: AIContextCategory[]) => void
 type ThemeCallback = (theme: ThemeInfo) => void
 
+export interface AIProviderSelection { provider: 'auto' | 'local' | 'claude' | 'openai' | 'routstr'; model: string }
+const providerCallbacks = new Set<(selection: AIProviderSelection) => void>()
+let currentProvider: AIProviderSelection | null = null
+
 let requestId = 0
 const pendingRequests = new Map<string, {
   resolve: (value: unknown) => void
@@ -80,12 +84,19 @@ function postToParent(msg: unknown) {
 
 function handleMessage(event: MessageEvent) {
   // Always validate origin — reject if not configured or mismatched
-  if (!allowedOrigin || event.origin !== allowedOrigin) return
+  if (!allowedOrigin || event.origin !== allowedOrigin || event.source !== window.parent) return
 
   const msg = event.data
   if (!msg || typeof msg.type !== 'string') return
 
   switch (msg.type) {
+    case 'ai:provider-configured': {
+      if (!['auto', 'local', 'claude', 'openai', 'routstr'].includes(msg.provider)) break
+      const selection = { provider: msg.provider as AIProviderSelection['provider'], model: typeof msg.model === 'string' ? msg.model : '' }
+      currentProvider = selection
+      for (const callback of providerCallbacks) callback(selection)
+      break
+    }
     case 'context:response': {
       const pending = pendingRequests.get(msg.id)
       if (pending) {
@@ -223,11 +234,21 @@ export const archyBridge = {
     }
   },
 
+  requestAISetup(reason?: 'funding') { postToParent({ type: 'ai:setup-request', ...(reason ? { reason } : {}) }) },
+
+  onProviderConfigured(callback: (selection: AIProviderSelection) => void) {
+    providerCallbacks.add(callback)
+    if (currentProvider) callback(currentProvider)
+    return () => { providerCallbacks.delete(callback) }
+  },
+
   /** Clean up listeners */
   destroy() {
     window.removeEventListener('message', handleMessage)
     pendingRequests.clear()
     initialized = false
+    currentProvider = null
+    allowedOrigin = null
   },
 
   /** Check if running inside Archy iframe */

aiui/packages/app/src/styles/main.css

@@ -57,12 +57,8 @@ body {
   width: 100%;
   height: 100%;
   overflow: hidden;
-  /* Every page paints its own explicit background (bg-[#0a0a0a] / bg-[#faf9f6])
-     EXCEPT the embedded Chat page, which intentionally goes transparent so
-     Archy's own dark chrome can show behind it (Chat.vue's iframe host). With
-     no background-color here, "transparent" fell through to the browser's
-     default white canvas instead. Match the theme's own dark/light default so
-     nothing above this ever needs to guess. */
+  /* Standalone canvas fallback. Embedded mode overrides this below so
+     Archy's wallpaper remains visible through the iframe. */
   background-color: #0a0a0a;
 }
 
@@ -70,6 +66,19 @@ html.light body {
   background-color: #faf9f6;
 }
 
+/* The host owns the wallpaper when AIUI is embedded. The document canvas
+   must be transparent too, otherwise it hides the host behind ChatPage. */
+html.aiui-embedded {
+  /* Match Archy's dark canvas scheme. Browsers otherwise give an iframe
+     with a different scheme an opaque canvas despite transparent CSS. */
+  color-scheme: dark;
+}
+
+html.aiui-embedded,
+html.aiui-embedded body {
+  background: transparent;
+}
+
 /* ===== DARK MODE GLASSMORPHISM — from Archy ===== */
 
 @layer components {

app-catalog/catalog.json

@@ -378,13 +378,13 @@
     {
       "id": "mempool",
       "title": "Mempool Explorer",
-      "version": "3.0.0",
+      "version": "3.3.1-archy1",
       "description": "Bitcoin mempool and blockchain explorer. Real-time transaction and block visualization.",
       "icon": "/assets/img/app-icons/mempool.webp",
       "author": "Mempool",
       "category": "money",
       "tier": "core",
-      "dockerImage": "source.archipelago-foundation.org/lfg2025/mempool-frontend:v3.3.1",
+      "dockerImage": "source.archipelago-foundation.org/chaum/mempool-frontend:v3.3.1-archy1",
       "repoUrl": "https://github.com/mempool/mempool",
       "requires": [
         "bitcoin-knots",
@@ -436,13 +436,13 @@
     {
       "id": "nginx-proxy-manager",
       "title": "Nginx Proxy Manager",
-      "version": "2.12.1",
-      "description": "Reverse proxy with SSL. Beautiful web interface for managing proxies. On a node, this manages its admin UI and upstream configuration — the proxy's own :80/:443 listeners are not published (the node's web server owns those ports).",
+      "version": "2.14.0",
+      "description": "Reverse proxy with SSL. Beautiful web interface for managing proxies. The node's public web server forwards configured domains through this service, preserving its access lists, certificates and custom routes.",
       "icon": "/assets/img/app-icons/nginx.svg",
       "author": "Nginx Proxy Manager",
       "category": "networking",
       "tier": "optional",
-      "dockerImage": "source.archipelago-foundation.org/lfg2025/nginx-proxy-manager:latest",
+      "dockerImage": "source.archipelago-foundation.org/lfg2025/nginx-proxy-manager@sha256:8b91afcca90f5f2a7b2b8937999824f623c8a8748ae8013a1c9bf94f62177f08",
       "repoUrl": "https://github.com/NginxProxyManager/nginx-proxy-manager"
     },
     {
@@ -644,6 +644,35 @@
           "/var/lib/archipelago/vaultwarden:/data"
         ]
       }
+    },
+    {
+      "id": "angor-indexer",
+      "title": "Angor Indexer",
+      "version": "1.0.2",
+      "description": "Bitcoin indexer endpoint for Angor with the existing Mempool explorer. Reuses this node’s Mempool and Electrum index; requires a synced, unpruned Bitcoin node. Add this service’s address as the custom indexer in Angor settings. A relay is optional and installed separately.",
+      "dockerImage": "source.archipelago-foundation.org/chaum/angor-indexer:1.0.2",
+      "author": "Angor / Archipelago",
+      "requires": [
+        "Mempool API",
+        "Unpruned Bitcoin"
+      ],
+      "category": "money",
+      "tier": "optional",
+      "icon": "/assets/img/app-icons/angor-green.png",
+      "repoUrl": "https://github.com/block-core/angor"
+    },
+    {
+      "id": "angor-relay",
+      "title": "Angor Relay",
+      "version": "1.1.2",
+      "description": "Optional dedicated Nostr relay for Angor project metadata. Separate storage and access settings keep the node’s internal relay private. Add this service’s address to Angor’s relay settings; use WSS for browser clients.",
+      "dockerImage": "source.archipelago-foundation.org/chaum/angor-relay:1.1.2",
+      "author": "Angor / Archipelago",
+      "requires": [],
+      "category": "nostr",
+      "tier": "optional",
+      "icon": "/assets/img/app-icons/angor-green.png",
+      "repoUrl": "https://github.com/hoytech/strfry"
     }
   ]
 }

apps/DEVELOPMENT.md

@@ -91,3 +91,5 @@ Adding a new app requires updates in multiple places:
 ## Port Assignments
 
 See [PORTS.md](./PORTS.md) for complete mapping. Dev ports are offset by +10000.
+
+Before submitting an app, complete **Launch acceptance: credentials, signer, and HTTP nodes** in `docs/app-developer-guide.md`. A generated password needs an authenticated credential interstitial; native Nostr login needs a tested first-launch chooser. Container health alone is not launch acceptance.

apps/angor-indexer/README.md

@@ -0,0 +1,109 @@
+# Angor Indexer
+
+Mainnet indexer endpoint for Angor, serving the existing Mempool explorer at
+the same origin. The service reuses this node's Mempool frontend/backend and
+Electrum index instead of creating another explorer or blockchain database.
+An unpruned, fully synced Bitcoin node is required. Installing against a pruned
+node must show the existing archival-node requirement; it must never silently
+unprune or replace its Bitcoin data.
+
+## Connect Angor
+
+Install **Angor Indexer** in the store. Its API appears under **Services**.
+In Angor settings, use `http://<node-address>:8998/` as the custom indexer origin.
+The `/health` endpoint reports readiness against Mempool's indexed block height;
+it returns 503 while that backend is unavailable. Index building may take time.
+
+Browser clients require a reachable HTTPS origin with a trusted certificate.
+Configure your HTTPS reverse proxy to forward to port 8998, then use that HTTPS
+origin in Angor. Do not disable browser TLS checks. The API supports both
+`/api/v1/` and `/api/` paths, transaction broadcast, and CORS without cookies.
+
+This endpoint intentionally exposes public blockchain queries and transaction
+broadcast through the app gate without dashboard-cookie login. It has no Bitcoin
+RPC password, wallet keys, or persistent wallet data. The backend stays on the
+managed container network; its private port does not become publicly exposed.
+You can change network access using the node's normal access controls.
+
+## Relay
+
+A relay is optional. Angor can continue using its configured external relays.
+Install **Angor Relay** separately to host project metadata locally, then add
+`ws://<node-address>:8091/` in Angor, or a trusted `wss://` proxy origin for browser
+clients. Its storage and configuration are separate from the node's internal
+relay; installing or uninstalling it does not change the internal relay.
+
+## Verify the complete client flow
+
+The root URL opens the Mempool explorer. `/health` and fee
+estimates establish API availability; they do not prove that project discovery,
+address history, or browser CORS works. Test a known funded project's address
+history, its original Nostr announcement, the Explore page, and project details
+in the actual Angor client. A certificate alone does not establish public routing.
+
+Keep existing discovery relays when adding a new relay. A new relay has no
+historical project data and does not automatically replicate other relays.
+Even with existing relays, an empty Explore page can be a client discovery
+failure: Angor Hub v2.0.0 was observed to stop after a batch whose announcements
+all failed on-chain validation. The same failure reproduced with our indexer
+and Angor's public indexer. Do not bypass the funding transaction's event-ID
+commitment or substitute an unsigned announcement to make a project appear.
+
+For opt-in read-only browser acceptance, install the frontend test dependencies
+and Playwright Chromium, then run:
+
+```sh
+ANGOR_TEST_INDEXER=https://indexer.example.com/ \
+ANGOR_TEST_RELAY=wss://relay.example.com/ \
+ANGOR_TEST_RELAYS='["wss://relay.angor.io","wss://relay.example.com/"]' \
+node tests/lifecycle/angor-public-browser.cjs
+```
+
+The relay under test must already contain the known original public project
+announcement documented in the test. The test does not import events, send
+funds, change your browser profile, or disable TLS verification. It checks the
+funding transaction/event commitment and real browser discovery and details.
+Relay signed writes, invalid-signature rejection, persistence, full node sync,
+and proxy upgrade/renewal tests remain separate acceptance requirements.
+
+## Packaging
+
+Build the pinned image with:
+
+```
+podman build -t source.archipelago-foundation.org/chaum/angor-indexer:1.0.2 apps/angor-indexer/container
+```
+
+The image runs as UID 101 with a read-only root filesystem and no capabilities.
+Only temporary nginx state is writable. Runtime DNS is read from resolv.conf so
+Mempool recreation does not require editing IP addresses or restarting this app.
+No app-specific Rust installer is required.
+
+Source documentation: [Angor's official deployment guide](https://github.com/block-core/angor/blob/869dd43cf38332dd7128a284a6bf4c1cac44c1a7/docker/DEPLOY-INDEXER-AND-RELAY.md).
+The app icon is based on [Angor’s dark-mode app icon](https://angor.io/images/app-icon-dark-mode.png), retrieved 2026-09-30. At the operator’s request, the outer corners use the same green as the background. The built-in imagegen edit preserved the black mark and filled the square green; the project asset is `neode-ui/public/assets/img/app-icons/angor-green.png`.
+
+Tests and release acceptance are recorded in the next-release checklist. The
+health probe establishes backend availability, not a guarantee that every
+address query is indexed at the latest Bitcoin tip.
+
+Install Mempool Explorer first. The declarative `install_prerequisites` check
+refuses a new adapter installation if its Mempool API component is absent, before
+creating an installed-app record. It does not install or resync Bitcoin for you.
+
+## Explorer on the public indexer origin
+
+The linked official deployment guide exposes **Mempool frontend and API together**
+on the public indexer URL. It uses standard Mempool images and requires no custom
+Angor fork or `ANGOR_ENABLED` flag.
+
+The operator now requires that same browser experience: opening the configured
+indexer domain must show the existing Mempool explorer, while Angor API requests
+continue working on that origin. Reuse the existing Mempool stack, including its
+live WebSocket feed; do not install a second explorer or blockchain database.
+
+**Candidate 1.0.2:** `/` and frontend paths proxy to the existing Mempool
+frontend; `/api/`, `/api/v1/`, `/health` and the WebSocket feed retain their
+indexer routes. Version 1.0.1 served only service JSON at `/`. The candidate
+remains pending deployment/release acceptance, which must cover assets and deep links,
+desktop/mobile rendering, WebSocket updates, API/CORS/broadcast, trusted HTTPS,
+restart/upgrade and management-access isolation before documenting it as shipped.

apps/angor-indexer/container/Dockerfile

@@ -0,0 +1,6 @@
+FROM docker.io/library/nginx:1.31.3-alpine@sha256:1d40e3eb3bf4f138de1d67193f2aa5309fcaf343eb5ffadbf5e9439de1eb1ebb
+COPY nginx.conf /etc/angor-nginx.conf.template
+COPY entrypoint.sh /usr/local/bin/angor-indexer
+USER 101:101
+EXPOSE 8080
+ENTRYPOINT ["/usr/local/bin/angor-indexer"]

apps/angor-indexer/container/entrypoint.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+set -eu
+# Resolve through the container runtime's DNS, including after dependency
+# recreation. Never bake a container IP into the indexer endpoint.
+DNS_RESOLVER=$(awk '/^nameserver[[:space:]]/ {print $2; exit}' /etc/resolv.conf)
+case "$DNS_RESOLVER" in
+  ''|*[!0-9a-fA-F.:]*) echo 'Container DNS resolver is unavailable' >&2; exit 1 ;;
+esac
+case "$DNS_RESOLVER" in *:*) DNS_RESOLVER="[$DNS_RESOLVER]" ;; esac
+export DNS_RESOLVER
+envsubst '${DNS_RESOLVER}' < /etc/angor-nginx.conf.template > /tmp/nginx.conf
+exec nginx -c /tmp/nginx.conf -g 'daemon off;'

apps/angor-indexer/container/nginx.conf

@@ -0,0 +1,81 @@
+worker_processes 1;
+pid /tmp/nginx.pid;
+error_log /dev/stderr warn;
+events { worker_connections 512; }
+http {
+    access_log off;
+    server_tokens off;
+    client_body_temp_path /tmp/client_temp;
+    proxy_temp_path /tmp/proxy_temp;
+    fastcgi_temp_path /tmp/fastcgi_temp;
+    uwsgi_temp_path /tmp/uwsgi_temp;
+    scgi_temp_path /tmp/scgi_temp;
+    resolver ${DNS_RESOLVER} valid=10s ipv6=off;
+    upstream mempool_backend {
+        zone mempool_backend 64k;
+        server mempool-api:8999 resolve;
+    }
+    upstream mempool_frontend {
+        zone mempool_frontend 64k;
+        server mempool:8080 resolve;
+    }
+    map $http_upgrade $angor_connection_upgrade {
+        default upgrade;
+        '' close;
+    }
+    server {
+        listen 8080;
+        client_max_body_size 4m;
+        proxy_connect_timeout 5s;
+        proxy_read_timeout 60s;
+        proxy_send_timeout 30s;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header Connection $angor_connection_upgrade;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Authorization "";
+        proxy_set_header Cookie "";
+        proxy_hide_header Access-Control-Allow-Origin;
+        add_header Access-Control-Allow-Origin '*' always;
+        add_header Access-Control-Allow-Methods 'GET, HEAD, POST, OPTIONS' always;
+        add_header Access-Control-Allow-Headers 'Content-Type' always;
+        add_header Cache-Control 'no-store' always;
+        if ($request_method = OPTIONS) { return 204; }
+        # Mempool's backend uses /api/v1. Match its frontend's shorter /api
+        # surface too, without doubling already-versioned Angor URLs.
+        rewrite ^/api/(?!v1/)(.*)$ /api/v1/$1 last;
+        # Readiness checks the indexing backend, not this gateway's process.
+        location = /health {
+            limit_except GET { deny all; }
+            proxy_pass http://mempool_backend/api/v1/blocks/tip/height;
+            proxy_intercept_errors on;
+            error_page 500 502 503 504 =503 @waiting;
+        }
+        location @waiting {
+            default_type application/json;
+            return 503 '{"status":"waiting","message":"Waiting for Bitcoin and Mempool indexing"}\n';
+        }
+        location ~ ^/api/(v1/)?tx$ {
+            limit_except GET POST { deny all; }
+            proxy_pass http://mempool_backend;
+        }
+        location = /api/v1/ws {
+            limit_except GET { deny all; }
+            proxy_read_timeout 600s;
+            proxy_send_timeout 600s;
+            proxy_pass http://mempool_backend;
+        }
+        location /api/ {
+            limit_except GET { deny all; }
+            proxy_pass http://mempool_backend;
+        }
+        # Share the already-installed explorer; no second frontend or index DB.
+        # Its SPA handles transaction/block deep links and static assets.
+        location / {
+            limit_except GET { deny all; }
+            proxy_pass http://mempool_frontend;
+            proxy_intercept_errors on;
+            error_page 500 502 503 504 =503 @waiting;
+        }
+    }
+}

apps/angor-indexer/manifest.yml

@@ -0,0 +1,73 @@
+app:
+  id: angor-indexer
+  name: Angor Indexer
+  version: 1.0.2
+  description: Bitcoin indexer endpoint for Angor with the existing Mempool explorer.
+    Reuses this node’s Mempool
+    and Electrum index; requires a synced, unpruned Bitcoin node. Add this service’s
+    address as the custom indexer in Angor settings. A relay is optional and installed
+    separately.
+  category: money
+  install_prerequisites:
+  - mempool
+  - mempool-api
+  upstream:
+    kind: github
+    repo: block-core/angor
+  container:
+    image: source.archipelago-foundation.org/chaum/angor-indexer:1.0.2
+    pull_policy: if-not-present
+    network: archy-net
+  dependencies:
+  - app_id: mempool
+    version: '>=3.0.0'
+  - app_id: mempool-api
+    version: '>=3.0.0'
+  - bitcoin:archival
+  resources:
+    cpu_limit: 1
+    memory_limit: 128Mi
+    disk_limit: 128Mi
+  security:
+    capabilities: []
+    readonly_root: true
+    no_new_privileges: true
+    user: 101
+    network_policy: isolated
+  ports:
+  - host: 8998
+    container: 8080
+    protocol: tcp
+    bind: 127.0.0.1
+    auth: open
+    auth_rationale: Public Bitcoin chain-data API and validated transaction broadcast for Angor clients; no wallet keys or node RPC credentials are exposed. Browser cookie login would break machine clients.
+  interfaces:
+    main:
+      name: Angor Indexer API
+      description: Use this origin as Angor’s custom mainnet indexer URL, or open it
+        to view the existing Mempool explorer. HTTPS is required for browser clients.
+      type: api
+      port: 8998
+      protocol: http
+      path: /
+  health_check:
+    type: http
+    endpoint: http://127.0.0.1:8080
+    path: /health
+    interval: 30s
+    timeout: 8s
+    retries: 3
+  bitcoin_integration:
+    rpc_access: none
+    sync_required: true
+    pruning_support: false
+  metadata:
+    icon: /assets/img/app-icons/angor-green.png
+    tier: optional
+    repo: https://github.com/block-core/angor
+    features:
+    - Angor mainnet API
+    - Mempool explorer on the same origin
+    - Reuses existing Mempool indexing
+    - No separate blockchain database
+    - Optional independent relay

apps/angor-relay/README.md

@@ -0,0 +1,33 @@
+# Angor Relay
+
+Optional standalone strfry relay for Angor's public project metadata. See
+[Angor Indexer setup](../angor-indexer/README.md) for client URLs and HTTPS/WSS.
+
+The gate exposes port 8091 for Nostr clients. strfry validates event signatures;
+this is a public relay, not a private messaging archive. It mounts only
+`/var/lib/archipelago/angor-relay` and its separate configuration directory.
+It never opens, reconfigures or shares the node's internal strfry database.
+
+For a public domain, proxy HTTPS to node port **8091**, enable WebSocket upgrade,
+and add `wss://your-relay-domain/` in Angor. Test both NIP-11 metadata (send
+`Accept: application/nostr+json`) and a real Nostr subscription over WSS. An
+Archipelago login page at this domain is a routing failure, not relay readiness.
+
+New relays start without project history. Keep existing discovery relays alongside
+yours until the needed original signed announcements and metadata are available
+locally. Relays do not automatically synchronize. Any history import must retain
+the original event IDs and signatures; verify funded projects against their
+on-chain commitments. A working WebSocket with zero stored events is not proof
+that the client's project discovery works. See the indexer README's browser test.
+
+The configuration is seeded only when absent, preserving operator changes.
+Stop the service before making a consistent backup of its event database.
+Ordinary start/restart/recreation preserves both mounts. Use the standard app
+lifecycle; do not manually recreate a systemd-managed container.
+
+## Image provenance
+
+Mirrored from `docker.io/dockurr/strfry:1.1.2`, upstream manifest digest
+`sha256:e81d238db13507f6ef24c49d47cd0b0ea58ff207961f10581fa2a7c901054df4`.
+The public Angor policy is supplied by this app's own configuration; it does not
+reuse the internal relay's event whitelist.

apps/angor-relay/manifest.yml

@@ -0,0 +1,223 @@
+app:
+  id: angor-relay
+  name: Angor Relay
+  version: 1.1.2
+  upstream:
+    kind: github
+    repo: hoytech/strfry
+  description: Optional dedicated Nostr relay for Angor project metadata. Separate
+    storage and access settings keep the node’s internal relay private. Add this service’s
+    address to Angor’s relay settings; use WSS for browser clients.
+  container:
+    image: source.archipelago-foundation.org/chaum/angor-relay:1.1.2
+    pull_policy: if-not-present
+  dependencies:
+  - storage: 5Gi
+  resources:
+    cpu_limit: 1
+    memory_limit: 512Mi
+    disk_limit: 5Gi
+  security:
+    capabilities: []
+    readonly_root: true
+    no_new_privileges: true
+    seccomp_profile: default
+    network_policy: isolated
+    apparmor_profile: nostr-relay
+  ports:
+  - host: 8091
+    container: 7777
+    protocol: tcp
+    bind: 127.0.0.1
+    auth: open
+    auth_rationale: Dedicated public Nostr relay for Angor project metadata; strfry verifies event signatures. It has separate storage from the private node relay and no wallet or node credentials.
+  volumes:
+  - type: bind
+    source: /var/lib/archipelago/angor-relay
+    target: /app/strfry-db
+    options:
+    - rw
+  - type: bind
+    source: /var/lib/archipelago/angor-relay-config/angor-relay.conf
+    target: /etc/strfry.conf
+    options:
+    - ro
+  files:
+  - path: /var/lib/archipelago/angor-relay-config/angor-relay.conf
+    overwrite: false
+    content: |
+      ##
+      ## Default strfry config
+      ##
+
+      # Directory that contains the strfry LMDB database (restart required)
+      db = "./strfry-db/"
+
+      dbParams {
+          # Maximum number of threads/processes that can simultaneously have LMDB transactions open (restart required)
+          maxreaders = 256
+
+          # Size of mmap() to use when loading LMDB (default is 10TB, does *not* correspond to disk-space used) (restart required)
+          mapsize = 10995116277760
+
+          # Disables read-ahead when accessing the LMDB mapping. Reduces IO activity when DB size is larger than RAM. (restart required)
+          noReadAhead = false
+      }
+
+      events {
+          # Maximum size of normalised JSON, in bytes
+          maxEventSize = 65536
+
+          # Events newer than this will be rejected
+          rejectEventsNewerThanSeconds = 900
+
+          # Events older than this will be rejected
+          rejectEventsOlderThanSeconds = 94608000
+
+          # Ephemeral events older than this will be rejected
+          rejectEphemeralEventsOlderThanSeconds = 60
+
+          # Ephemeral events will be deleted from the DB when older than this
+          ephemeralEventsLifetimeSeconds = 300
+
+          # Maximum number of tags allowed
+          maxNumTags = 2000
+
+          # Maximum size for tag values, in bytes
+          maxTagValSize = 1024
+      }
+
+      relay {
+          # Interface to listen on. Use 0.0.0.0 to listen on all interfaces (restart required)
+          bind = "0.0.0.0"
+
+          # Port to open for the nostr websocket protocol (restart required)
+          port = 7777
+
+          # Set OS-limit on maximum number of open files/sockets (if 0, don't attempt to set) (restart required)
+          nofiles = 0
+
+          # HTTP header that contains the client's real IP, before reverse proxying (ie x-real-ip) (MUST be all lower-case)
+          realIpHeader = ""
+
+          info {
+              # NIP-11: Name of this server. Short/descriptive (< 30 characters)
+              name = "Angor Relay"
+
+              # NIP-11: Detailed information about relay, free-form
+              description = "Dedicated public relay for Angor project metadata."
+
+              # NIP-11: Administrative nostr pubkey, for contact purposes
+              pubkey = ""
+
+              # NIP-11: Alternative administrative contact (email, website, etc)
+              contact = ""
+
+              # NIP-11: URL pointing to an image to be used as an icon for the relay
+              icon = ""
+
+              # List of supported lists as JSON array, or empty string to use default. Example: "[1,2]"
+              nips = ""
+          }
+
+          # Maximum accepted incoming websocket frame size (should be larger than max event) (restart required)
+          maxWebsocketPayloadSize = 131072
+
+          # Maximum number of filters allowed in a REQ
+          maxReqFilterSize = 200
+
+          # Websocket-level PING message frequency (should be less than any reverse proxy idle timeouts) (restart required)
+          autoPingSeconds = 55
+
+          # If TCP keep-alive should be enabled (detect dropped connections to upstream reverse proxy)
+          enableTcpKeepalive = false
+
+          # How much uninterrupted CPU time a REQ query should get during its DB scan
+          queryTimesliceBudgetMicroseconds = 10000
+
+          # Maximum records that can be returned per filter
+          maxFilterLimit = 500
+
+          # Maximum number of subscriptions (concurrent REQs) a connection can have open at any time
+          maxSubsPerConnection = 20
+
+          writePolicy {
+              # If non-empty, path to an executable script that implements the writePolicy plugin logic
+              plugin = ""
+          }
+
+          compression {
+              # Use permessage-deflate compression if supported by client. Reduces bandwidth, but slight increase in CPU (restart required)
+              enabled = true
+
+              # Maintain a sliding window buffer for each connection. Improves compression, but uses more memory (restart required)
+              slidingWindow = true
+          }
+
+          logging {
+              # Dump all incoming messages
+              dumpInAll = false
+
+              # Dump all incoming EVENT messages
+              dumpInEvents = false
+
+              # Dump all incoming REQ/CLOSE messages
+              dumpInReqs = false
+
+              # Log performance metrics for initial REQ database scans
+              dbScanPerf = false
+
+              # Log reason for invalid event rejection? Can be disabled to silence excessive logging
+              invalidEvents = true
+          }
+
+          numThreads {
+              # Ingester threads: route incoming requests, validate events/sigs (restart required)
+              ingester = 3
+
+              # reqWorker threads: Handle initial DB scan for events (restart required)
+              reqWorker = 3
+
+              # reqMonitor threads: Handle filtering of new events (restart required)
+              reqMonitor = 3
+
+              # negentropy threads: Handle negentropy protocol messages (restart required)
+              negentropy = 2
+          }
+
+          negentropy {
+              # Support negentropy protocol messages
+              enabled = true
+
+              # Maximum records that sync will process before returning an error
+              maxSyncEvents = 1000000
+          }
+      }
+  health_check:
+    type: http
+    endpoint: http://127.0.0.1:7777
+    path: /health
+    interval: 30s
+    timeout: 5s
+    retries: 3
+  nostr_integration:
+    relay_type: public
+    monetization_enabled: false
+  category: nostr
+  interfaces:
+    main:
+      name: Angor Relay
+      description: Nostr WebSocket endpoint; use ws:// for LAN or wss:// through your
+        HTTPS domain.
+      type: api
+      port: 8091
+      protocol: http
+      path: /
+  metadata:
+    icon: /assets/img/app-icons/angor-green.png
+    tier: optional
+    repo: https://github.com/hoytech/strfry
+    features:
+    - Angor project metadata
+    - Separate from the node relay
+    - Persistent Nostr event storage

apps/archy-mempool-web/manifest.yml

@@ -1,7 +1,7 @@
 app:
   id: archy-mempool-web
   name: Mempool Web
-  version: 3.0.1
+  version: 3.3.1-archy1
   # Where this app comes from, so scripts/check-upstream-releases.py can
   # tell us when the pin below has fallen behind. Without it nothing can:
   # container.image names our mirror, not the project it was mirrored from.
@@ -12,7 +12,7 @@ app:
   container_name: mempool
 
   container:
-    image: source.archipelago-foundation.org/lfg2025/mempool-frontend:v3.3.1
+    image: source.archipelago-foundation.org/chaum/mempool-frontend:v3.3.1-archy1
     pull_policy: if-not-present
     network: archy-net
 
@@ -45,7 +45,9 @@ app:
     # first, but nginx binds 0.0.0.0:8080 (IPv4) only -> localhost probe gets
     # "connection refused" -> perpetual unhealthy -> health_monitor restart loop.
     endpoint: http://127.0.0.1:8080
-    path: /
+    # Probe the backend through nginx: a static page can be healthy while
+    # every API/WebSocket request is stuck on a dead backend address.
+    path: /api/v1/backend-info
     interval: 30s
     timeout: 5s
     retries: 3

apps/bitcoin-core/manifest.yml

@@ -54,7 +54,7 @@ app:
         if [ -n "$RPC_TXRELAY_AUTH" ]; then
           RPC_TXRELAY_FLAGS="$RPC_TXRELAY_FLAGS -rpcauth=$RPC_TXRELAY_AUTH -rpcwhitelist=txrelay:sendrawtransaction,submitpackage,testmempoolaccept,getmempoolinfo,getrawmempool,getmempoolentry,getnetworkinfo,getblockchaininfo,getblockcount,getblockhash,getblock,getblockheader,getrawtransaction,gettxout,gettxspendingprevout,decoderawtransaction,decodescript,estimatesmartfee,uptime,ping,getconnectioncount,getpeerinfo,getindexinfo,getdeploymentinfo,getchaintips";
         fi;
-        if [ "${DISK_GB_VALUE:-0}" -lt 1000 ]; then
+        if [ "${BITCOIN_PRUNE:-0}" = "1" ] || [ "${DISK_GB_VALUE:-0}" -lt 1000 ]; then
           exec "$BITCOIND" -datadir=/home/bitcoin/.bitcoin -conf="$RPC_CONF" -allowignoredconf=1 -printtoconsole=0 -server=1 -prune=50000 -rpcallowip=0.0.0.0/0 -rpcbind=0.0.0.0:8332 -listen=1 -bind=0.0.0.0:8333 -dbcache=1024 -par=0 -maxconnections=125 $RPC_HEADROOM $RPC_TXRELAY_FLAGS;
         else
           exec "$BITCOIND" -datadir=/home/bitcoin/.bitcoin -conf="$RPC_CONF" -allowignoredconf=1 -printtoconsole=0 -server=1 -txindex=1 -rpcallowip=0.0.0.0/0 -rpcbind=0.0.0.0:8332 -listen=1 -bind=0.0.0.0:8333 -dbcache=4096 -par=0 -maxconnections=125 $RPC_HEADROOM $RPC_TXRELAY_FLAGS;

apps/bitcoin-knots/manifest.yml

@@ -60,7 +60,7 @@ app:
         if [ -n "$RPC_TXRELAY_AUTH" ]; then
           RPC_TXRELAY_FLAGS="$RPC_TXRELAY_FLAGS -rpcauth=$RPC_TXRELAY_AUTH -rpcwhitelist=txrelay:sendrawtransaction,submitpackage,testmempoolaccept,getmempoolinfo,getrawmempool,getmempoolentry,getnetworkinfo,getblockchaininfo,getblockcount,getblockhash,getblock,getblockheader,getrawtransaction,gettxout,gettxspendingprevout,decoderawtransaction,decodescript,estimatesmartfee,uptime,ping,getconnectioncount,getpeerinfo,getindexinfo,getdeploymentinfo,getchaintips";
         fi;
-        if [ "${DISK_GB_VALUE:-0}" -lt 1000 ]; then
+        if [ "${BITCOIN_PRUNE:-0}" = "1" ] || [ "${DISK_GB_VALUE:-0}" -lt 1000 ]; then
           exec "$BITCOIND" -datadir=/home/bitcoin/.bitcoin -conf="$RPC_CONF" -allowignoredconf=1 -printtoconsole=0 -server=1 -prune=50000 -rpcallowip=0.0.0.0/0 -rpcbind=0.0.0.0:8332 -listen=1 -bind=0.0.0.0:8333 -dbcache=2048 -par=0 -maxconnections=125 $RPC_HEADROOM $RPC_TXRELAY_FLAGS;
         else
           exec "$BITCOIND" -datadir=/home/bitcoin/.bitcoin -conf="$RPC_CONF" -allowignoredconf=1 -printtoconsole=0 -server=1 -txindex=1 -rpcallowip=0.0.0.0/0 -rpcbind=0.0.0.0:8332 -listen=1 -bind=0.0.0.0:8333 -dbcache=4096 -par=0 -maxconnections=125 $RPC_HEADROOM $RPC_TXRELAY_FLAGS;

apps/gitea/manifest.yml

@@ -15,6 +15,9 @@ app:
     image: source.archipelago-foundation.org/lfg2025/gitea:1.27.3
     pull_policy: if-not-present
 
+  # Preserve repositories, database, keys and configuration during runtime repairs.
+  backup_before_runtime_change: true
+
   dependencies:
     # Source history, LFS objects, release artifacts and OCI layers all share
     # this persistent store. 500Mi was only suitable for an empty demo node.
@@ -25,7 +28,7 @@ app:
     disk_limit: 50Gi
 
   security:
-    capabilities: [CHOWN, FOWNER, SETUID, SETGID, DAC_OVERRIDE, NET_BIND_SERVICE]
+    capabilities: [CHOWN, FOWNER, SETUID, SETGID, DAC_OVERRIDE, NET_BIND_SERVICE, SYS_CHROOT]
     readonly_root: false
     no_new_privileges: false
     network_policy: bridge
@@ -62,6 +65,17 @@ app:
       target: /etc/gitea
       options: [rw]
 
+  # Seed a fresh installation with the same origin advertised by the app gate.
+  # Existing app.ini (including custom HTTPS/domain settings) is never replaced.
+  files:
+    - path: /var/lib/archipelago/gitea/data/gitea/conf/app.ini
+      overwrite: false
+      content: |
+        [server]
+        DOMAIN = {{HOST_IP}}
+        SSH_DOMAIN = {{HOST_IP}}
+        ROOT_URL = http://{{HOST_IP}}:3001/
+
   environment:
     - GITEA__database__DB_TYPE=sqlite3
     - GITEA__server__SSH_PORT=2222
@@ -106,10 +120,3 @@ app:
       - Issue tracking and pull requests
       - CI/CD via Gitea Actions
       - Lightweight SQLite deployment
-
-  nginx_proxy:
-    listen: 3000
-    proxy_pass: http://127.0.0.1:3001
-    extra_headers:
-      - proxy_hide_header X-Frame-Options
-      - proxy_hide_header Content-Security-Policy

apps/indeedhub-api/manifest.yml

@@ -15,6 +15,8 @@ app:
   container_name: indeedhub-api
 
   container:
+    # Public identity pins only; registration/publication stay disabled by default.
+    media_registration_identity: true
     image: source.archipelago-foundation.org/lfg2025/indeedhub-api:1.0.0
     pull_policy: if-not-present
     network: indeedhub-net

apps/indeedhub/manifest.yml

@@ -69,10 +69,10 @@ app:
       - copy_from_host:
           src: "web-ui/nostr-provider.js"
           dest: "/usr/share/nginx/html/nostr-provider.js"
-      - exec: ["sh", "-c", "grep -qF 'location = /nostr-provider.js {' /etc/nginx/conf.d/default.conf || sed -i '/location = \/sw.js {/i\\    location = /nostr-provider.js {\\n        add_header Cache-Control \"no-cache, no-store, must-revalidate\";\\n        expires off;\\n    }\\n' /etc/nginx/conf.d/default.conf"]
-      - exec: ["sh", "-c", "grep -q nostr-provider /etc/nginx/conf.d/default.conf || sed -i 's#</head>#<script src=\"/nostr-provider.js\"></script></head>#' /etc/nginx/conf.d/default.conf"]
-      - exec: ["sed", "-i", "s#tab-signer-v2#tab-signer-v4#g; s#tab-signer-v3#tab-signer-v4#g", "/etc/nginx/conf.d/default.conf"]
-      - exec: ["sed", "-i", "s#src=\"/nostr-provider.js\"#src=\"/nostr-provider.js?v=tab-signer-v4\"#g", "/etc/nginx/conf.d/default.conf"]
+      - exec: ["sh", "-c", "grep -qF 'location = /nostr-provider.js {' /etc/nginx/conf.d/default.conf || sed -i '/location = .*sw[.]js {/i\\    location = /nostr-provider.js {\\n        add_header Cache-Control \"no-cache, no-store, must-revalidate\";\\n        expires off;\\n    }\\n' /etc/nginx/conf.d/default.conf"]
+      - exec: ["sh", "-c", "if ! grep -qE '<script[^>]*nostr-provider' /usr/share/nginx/html/index.html && ! grep -qE '(sub_filter|<script).*nostr-provider' /etc/nginx/conf.d/default.conf; then sed -i 's#</head>#<script src=\"/nostr-provider.js\"></script></head>#' /usr/share/nginx/html/index.html; fi"]
+      - exec: ["sed", "-i", "s#tab-signer-v2#tab-signer-v4#g; s#tab-signer-v3#tab-signer-v4#g", "/etc/nginx/conf.d/default.conf", "/usr/share/nginx/html/index.html"]
+      - exec: ["sed", "-i", "s#src=\"/nostr-provider.js\"#src=\"/nostr-provider.js?v=tab-signer-v4\"#g", "/etc/nginx/conf.d/default.conf", "/usr/share/nginx/html/index.html"]
       - exec: ["nginx", "-s", "reload"]
 
   # TCP liveness on the nginx port, NOT an http GET of /. nginx binds 7777 at

apps/mempool/manifest.yml

@@ -1,7 +1,7 @@
 app:
   id: mempool
   name: Mempool Explorer
-  version: 3.0.0
+  version: 3.3.1-archy1
   # Where this app comes from, so scripts/check-upstream-releases.py can
   # tell us when the pin below has fallen behind. Without it nothing can:
   # container.image names our mirror, not the project it was mirrored from.
@@ -11,7 +11,7 @@ app:
   description: Bitcoin mempool and blockchain explorer. Real-time transaction and block visualization.
   
   container:
-    image: source.archipelago-foundation.org/lfg2025/mempool-frontend:v3.3.1
+    image: source.archipelago-foundation.org/chaum/mempool-frontend:v3.3.1-archy1
     image_signature: cosign://...
     pull_policy: if-not-present
     

apps/nginx-proxy-manager/manifest.yml

@@ -1,20 +1,23 @@
 app:
   id: nginx-proxy-manager
   name: Nginx Proxy Manager
-  version: 2.12.1
+  version: 2.14.0
   upstream:
     kind: github
     repo: NginxProxyManager/nginx-proxy-manager
   description: >-
     Reverse proxy with SSL. Beautiful web interface for managing proxies.
-    On a node, this manages its admin UI and upstream configuration — the
-    proxy's own :80/:443 listeners are not published (the node's web server
-    owns those ports).
+    The node's public web server forwards configured domains through this
+    service, preserving its access lists, certificates and custom routes.
+  backup_before_runtime_change: true
 
   container:
-    image: source.archipelago-foundation.org/lfg2025/nginx-proxy-manager:latest
+    image: source.archipelago-foundation.org/lfg2025/nginx-proxy-manager@sha256:8b91afcca90f5f2a7b2b8937999824f623c8a8748ae8013a1c9bf94f62177f08
     pull_policy: if-not-present
-    network: pasta
+    # Rootless pasta copies the LAN IP, preventing requests back to this node.
+    # Retain the old pasta host gateway used by saved NPM upstreams, plus
+    # host.containers.internal. This subnet stays inside the private rootless namespace.
+    network: slirp4netns:allow_host_loopback=true,cidr=169.254.1.0/24
 
   dependencies:
     - storage: 1Gi
@@ -49,6 +52,17 @@ app:
         Nginx Proxy Manager enforces its own admin account on every page;
         the initial setup wizard also has to answer before any account exists.
 
+    - host: 8088
+      container: 80
+      protocol: tcp
+      bind: 127.0.0.1
+      auth: local
+    - host: 8444
+      container: 443
+      protocol: tcp
+      bind: 127.0.0.1
+      auth: local
+
   volumes:
     - type: bind
       source: /var/lib/archipelago/nginx-proxy-manager
@@ -64,9 +78,11 @@ app:
 
   environment: []
 
+  # Probe the admin API inside the container, independent of optional
+  # tunnel listeners. This also verifies the Node backend is ready.
   health_check:
-    type: tcp
-    endpoint: localhost:81
+    type: http
+    endpoint: http://127.0.0.1:81/api/
     interval: 30s
     timeout: 5s
     retries: 3

apps/portainer/manifest.yml

@@ -14,8 +14,16 @@ app:
   container:
     image: source.archipelago-foundation.org/lfg2025/portainer:2.45.0
     pull_policy: if-not-present
+    # Portainer fetches Git sources and images from services on this same node.
+    # Rootless pasta copies the host LAN address into its namespace, so a LAN
+    # URL points back at Portainer itself. Give it a private address with the
+    # supported rootless slirp backend; public app URLs still traverse the gate.
+    network: slirp4netns
     data_uid: "1000:1000"
 
+  # Snapshot state before an upgrade recreates this app with new networking.
+  backup_before_runtime_change: true
+
   dependencies:
     - storage: 1Gi
 

catalog.json

@@ -67,13 +67,13 @@
     {
       "id": "mempool",
       "title": "Mempool Explorer",
-      "version": "3.0.0",
+      "version": "3.3.1-archy1",
       "description": "Bitcoin mempool and blockchain explorer. Real-time transaction and block visualization.",
       "icon": "/assets/img/app-icons/mempool.webp",
       "author": "Mempool",
       "category": "money",
       "tier": "core",
-      "dockerImage": "source.archipelago-foundation.org/lfg2025/mempool-frontend:v3.3.1",
+      "dockerImage": "source.archipelago-foundation.org/chaum/mempool-frontend:v3.3.1-archy1",
       "repoUrl": "https://github.com/mempool/mempool",
       "requires": [
         "bitcoin-knots",

core/Cargo.lock

@@ -104,7 +104,7 @@ dependencies = [
 
 [[package]]
 name = "archipelago"
-version = "1.8.13-alpha"
+version = "1.9.0-alpha"
 dependencies = [
  "anyhow",
  "archipelago-container",
@@ -137,9 +137,11 @@ dependencies = [
  "hyper 0.14.32",
  "hyper-util",
  "hyper-ws-listener",
+ "image",
  "iroh",
  "iroh-blobs",
  "libc",
+ "lightning-invoice",
  "lofty",
  "mainline",
  "mdns-sd",
@@ -1567,6 +1569,15 @@ version = "2.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"
 
+[[package]]
+name = "fdeflate"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c"
+dependencies = [
+ "simd-adler32",
+]
+
 [[package]]
 name = "fiat-crypto"
 version = "0.2.9"
@@ -2503,8 +2514,22 @@ checksum = "e6506c6c10786659413faa717ceebcb8f70731c0a60cbae39795fdf114519c1a"
 dependencies = [
  "bytemuck",
  "byteorder-lite",
+ "image-webp",
  "moxcms",
  "num-traits",
+ "png",
+ "zune-core",
+ "zune-jpeg",
+]
+
+[[package]]
+name = "image-webp"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "525e9ff3e1a4be2fbea1fdf0e98686a6d98b4d8f937e1bf7402245af1909e8c3"
+dependencies = [
+ "byteorder-lite",
+ "quick-error",
 ]
 
 [[package]]
@@ -3636,9 +3661,9 @@ dependencies = [
 
 [[package]]
 name = "nostr"
-version = "0.44.2"
+version = "0.44.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3aa5e3b6a278ed061835fe1ee293b71641e6bf8b401cfe4e1834bbf4ef0a34e1"
+checksum = "c7d3d987ea7078dc36947cde532637c472a229426702e4331dd7667325378bd9"
 dependencies = [
  "aes",
  "base64 0.22.1",
@@ -3681,9 +3706,9 @@ dependencies = [
 
 [[package]]
 name = "nostr-relay-pool"
-version = "0.44.0"
+version = "0.44.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4b1073ccfbaea5549fb914a9d52c68dab2aecda61535e5143dd73e95445a804b"
+checksum = "c85c54d6ca9aae4ae2bf19a7663ba9db5f45f783f1d24aff55f006386b8b99a1"
 dependencies = [
  "async-utility",
  "async-wsocket",
@@ -4142,6 +4167,19 @@ dependencies = [
  "time",
 ]
 
+[[package]]
+name = "png"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61"
+dependencies = [
+ "bitflags 2.13.0",
+ "crc32fast",
+ "fdeflate",
+ "flate2",
+ "miniz_oxide",
+]
+
 [[package]]
 name = "poly1305"
 version = "0.8.0"
@@ -4366,6 +4404,12 @@ dependencies = [
  "image",
 ]
 
+[[package]]
+name = "quick-error"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
+
 [[package]]
 name = "quick-xml"
 version = "0.39.4"
@@ -7322,3 +7366,18 @@ dependencies = [
  "log",
  "simd-adler32",
 ]
+
+[[package]]
+name = "zune-core"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb8a0807f7c01457d0379ba880ba6322660448ddebc890ce29bb64da71fb40f9"
+
+[[package]]
+name = "zune-jpeg"
+version = "0.5.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27bc9d5b815bc103f142aa054f561d9187d191692ec7c2d1e2b4737f8dbd7296"
+dependencies = [
+ "zune-core",
+]

core/archipelago/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "archipelago"
-version = "1.8.13-alpha"
+version = "1.9.0-alpha"
 edition = "2021"
 license.workspace = true
 description = "Archipelago Bitcoin Node OS - Native backend"
@@ -73,6 +73,7 @@ chrono = "0.4"
 
 # BIP-39 mnemonic seed generation + BIP-32 HD key derivation
 bip39 = { version = "2.1", features = ["rand"] }
+lightning-invoice = "=0.34.1"
 bitcoin = { version = "=0.32.5", features = ["rand-std"] }
 
 # Configuration
@@ -106,6 +107,8 @@ flate2 = "1.0"
 # TOTP 2FA
 totp-rs = { version = "5.7", features = ["otpauth", "gen_secret"] }
 qrcode = "0.14"
+# Paid image previews must be degraded on the server, never by browser CSS.
+image = { version = "0.25.9", default-features = false, features = ["jpeg", "png", "webp"] }
 data-encoding = "2.6"
 zeroize = { version = "1.8.2", features = ["derive"] }
 
@@ -146,6 +149,7 @@ iroh-blobs = { version = "0.103", optional = true }
 lofty = "0.24.0"
 cashu = { version = "0.17.5", default-features = false, features = ["wallet"] }
 
+tempfile = "3.10"
+
 [dev-dependencies]
 tokio-test = "0.4"
-tempfile = "3.10"

core/archipelago/src/api/handler/cloud_purchase.rs

@@ -0,0 +1,142 @@
+//! Permanent Cloud snapshot delivery. Current source path/share state cannot
+//! revoke a settled immutable snapshot; no rental clock is started here.
+use super::{build_response, ApiHandler};
+use crate::{
+    content_purchase::{Journal, SellerPhase},
+    content_server::ByteRange,
+};
+use anyhow::{Context, Result};
+use hyper::{Body, HeaderMap, Response, StatusCode};
+use tokio::io::{AsyncReadExt, AsyncSeekExt};
+impl ApiHandler {
+    pub(super) async fn handle_cloud_purchase(
+        &self,
+        path: &str,
+        headers: &HeaderMap,
+    ) -> Result<Response<Body>> {
+        let (content_id, purchase_id) = path
+            .strip_prefix("/content/")
+            .and_then(|value| value.split_once("/purchase/"))
+            .context("Invalid purchase delivery route")?;
+        anyhow::ensure!(
+            !content_id.contains('/')
+                && !content_id.starts_with("registered_")
+                && !purchase_id.contains('/'),
+            "Invalid Cloud delivery route"
+        );
+        let audience = crate::identity::did_key_from_pubkey_hex(&self.self_pubkey_hex)?;
+        let buyer = crate::content_auth::incoming(
+            headers,
+            &audience,
+            path,
+            chrono::Utc::now().timestamp(),
+        )?
+        .context("Authenticated peer proof is required")?;
+        let mut values = headers.get_all("x-content-capability").iter();
+        let capability = values
+            .next()
+            .context("Delivery capability is required")?
+            .to_str()?;
+        anyhow::ensure!(values.next().is_none(), "Duplicate delivery capability");
+        let (contract, mime) = {
+            let journal = Journal::open(&self.config.data_dir).await?;
+            let record = journal
+                .seller(purchase_id)
+                .await?
+                .context("Purchase settlement not found")?;
+            let receipt = match record.phase {
+                SellerPhase::ReceiptSaved(receipt) => receipt,
+                _ => anyhow::bail!("Purchase settlement is not durable"),
+            };
+            anyhow::ensure!(
+                record.contract.buyer_did == buyer
+                    && record.contract.seller_did == audience
+                    && record.contract.content_id == content_id
+                    && receipt.capability == capability,
+                "Purchase delivery binding changed"
+            );
+            let envelope = journal
+                .protocol_envelope("seller", purchase_id)
+                .await?
+                .context("Original delivery metadata is missing")?;
+            anyhow::ensure!(
+                envelope.contract()? == record.contract,
+                "Delivery metadata binding changed"
+            );
+            (record.contract, envelope.offer.mime_type)
+        };
+        let range = headers
+            .get("range")
+            .map(|value| -> Result<_> {
+                crate::content_server::parse_range_header(value.to_str()?).context("Invalid range")
+            })
+            .transpose()?;
+        let total = contract.content_size;
+        let (start, end, partial) = match range {
+            None => (0, total - 1, false),
+            Some(ByteRange::From { start, end }) => {
+                (start, end.unwrap_or(total - 1).min(total - 1), true)
+            }
+            Some(ByteRange::Suffix(count)) if count > 0 => {
+                (total.saturating_sub(count), total - 1, true)
+            }
+            _ => anyhow::bail!("Invalid range"),
+        };
+        if start > end || start >= total {
+            let mut response = build_response(
+                StatusCode::RANGE_NOT_SATISFIABLE,
+                "text/plain",
+                Body::empty(),
+            );
+            response
+                .headers_mut()
+                .insert("content-range", format!("bytes */{total}").parse()?);
+            return Ok(response);
+        }
+        let data = self.config.data_dir.clone();
+        let file = tokio::task::spawn_blocking(move || {
+            crate::content_snapshot::open_matching(
+                &data,
+                &contract.content_id,
+                &contract.content_sha256,
+                contract.content_size,
+            )
+        })
+        .await??;
+        let mut file = tokio::fs::File::from_std(file.file);
+        file.seek(std::io::SeekFrom::Start(start)).await?;
+        let length = end - start + 1;
+        let chunks =
+            futures_util::stream::try_unfold((file, length), |(mut file, left)| async move {
+                if left == 0 {
+                    return Ok::<_, std::io::Error>(None);
+                }
+                let mut bytes = vec![0; left.min(65536) as usize];
+                let count = file.read(&mut bytes).await?;
+                if count == 0 {
+                    return Err(std::io::Error::new(
+                        std::io::ErrorKind::UnexpectedEof,
+                        "Purchase snapshot ended early",
+                    ));
+                }
+                bytes.truncate(count);
+                Ok(Some((bytes, (file, left - count as u64))))
+            });
+        let mut response = Response::builder()
+            .status(if partial {
+                StatusCode::PARTIAL_CONTENT
+            } else {
+                StatusCode::OK
+            })
+            .header("content-type", mime)
+            .header("content-length", length)
+            .header("accept-ranges", "bytes")
+            .header("cache-control", "private, no-store")
+            .header("x-content-type-options", "nosniff")
+            .header("content-security-policy", "sandbox; default-src 'none'");
+        if partial {
+            response = response.header("content-range", format!("bytes {start}-{end}/{total}"));
+        }
+        Ok(response.body(Body::wrap_stream(chunks))?)
+    }
+}

core/archipelago/src/api/handler/content.rs

@@ -7,14 +7,48 @@ use hyper::{Response, StatusCode};
 use super::{is_valid_app_id, ApiHandler};
 
 impl ApiHandler {
-    pub(super) async fn handle_content_catalog(config: &Config) -> Result<Response<hyper::Body>> {
-        match content_server::load_catalog(&config.data_dir).await {
+    fn verified_content_peer(
+        &self,
+        path: &str,
+        headers: &hyper::HeaderMap,
+    ) -> Result<Option<String>> {
+        let audience = crate::identity::did_key_from_pubkey_hex(&self.self_pubkey_hex)?;
+        crate::content_auth::incoming(headers, &audience, path, chrono::Utc::now().timestamp())
+    }
+
+    async fn content_access_context(
+        &self,
+        path: &str,
+        headers: &hyper::HeaderMap,
+    ) -> Result<(Option<String>, bool, bool)> {
+        let peer = self.verified_content_peer(path, headers)?;
+        let known = if let Some(did) = &peer {
+            crate::federation::load_nodes(&self.config.data_dir)
+                .await?
+                .iter()
+                .any(|node| &node.did == did)
+        } else {
+            false
+        };
+        let owner = match crate::session::extract_session_cookie(headers) {
+            Some(token) => self.session_store.validate(&token).await,
+            None => false,
+        };
+        Ok((peer, known, owner))
+    }
+
+    pub(super) async fn handle_content_catalog(
+        &self,
+        headers: &hyper::HeaderMap,
+    ) -> Result<Response<hyper::Body>> {
+        let (peer, known, owner) = self.content_access_context("/content", headers).await?;
+        match content_server::load_catalog(&self.config.data_dir).await {
             Ok(catalog) => {
                 // Only expose public metadata for available items
                 let items: Vec<serde_json::Value> = catalog
                     .items
                     .iter()
-                    .filter(|i| !matches!(i.availability, content_server::Availability::Nobody))
+                    .filter(|item| content_server::visible_to(item, peer.as_deref(), known, owner))
                     .map(|i| {
                         serde_json::json!({
                             "id": i.id,
@@ -74,7 +108,7 @@ impl ApiHandler {
         let invoice_hash = headers
             .get("x-invoice-hash")
             .and_then(|v| v.to_str().ok())
-            .map(|s| s.to_string())
+            .map(|s| s.to_ascii_lowercase())
             .or_else(|| {
                 headers
                     .get("x-onchain-address")
@@ -82,11 +116,18 @@ impl ApiHandler {
                     .map(|s| s.to_string())
             });
 
-        // Extract federation peer DID from X-Federation-DID header
-        let peer_did = headers
-            .get("x-federation-did")
-            .and_then(|v| v.to_str().ok())
-            .map(|s| s.to_string());
+        let peer_did = match self.verified_content_peer(path, headers) {
+            Ok(peer) => peer,
+            Err(_) => {
+                return Ok(build_response(
+                    StatusCode::FORBIDDEN,
+                    "application/json",
+                    hyper::Body::from(
+                        r#"{"error":"Peer authentication failed. Check both nodes are updated and their clocks are correct."}"#,
+                    ),
+                ))
+            }
+        };
 
         // The authenticated local operator never pays for their own node's
         // content: validate the session cookie (same discipline as the model
@@ -98,11 +139,64 @@ impl ApiHandler {
             None => false,
         };
 
+        // Payment settlement is verified on the seller even when no status
+        // poll preceded this download (e.g. direct payment from another node).
+        let requires_payment = if !owner_session && headers.contains_key("x-invoice-hash") {
+            content_server::load_catalog(&config.data_dir)
+                .await?
+                .items
+                .iter()
+                .any(|item| {
+                    item.id == content_id
+                        && matches!(item.access, content_server::AccessControl::Paid { .. })
+                })
+        } else {
+            false
+        };
+        if requires_payment {
+            if let Some(hash) = headers.get("x-invoice-hash").and_then(|v| v.to_str().ok()) {
+                if hash.len() != 64 || !hash.bytes().all(|c| c.is_ascii_hexdigit()) {
+                    return Ok(build_response(
+                        StatusCode::BAD_REQUEST,
+                        "text/plain",
+                        hyper::Body::from("Invalid payment hash"),
+                    ));
+                }
+                if let Err(error) = self
+                    .rpc_handler
+                    .settle_content_invoice(hash, content_id)
+                    .await
+                {
+                    tracing::warn!("Cannot verify peer-file invoice settlement: {error:#}");
+                    return Ok(build_response(
+                        StatusCode::SERVICE_UNAVAILABLE,
+                        "application/json",
+                        hyper::Body::from(
+                            r#"{"error":"Payment verification is temporarily unavailable. Retry the download without paying again."}"#,
+                        ),
+                    ));
+                }
+            }
+        }
+
         // Parse Range header for streaming support
-        let range = headers
-            .get("range")
-            .and_then(|v| v.to_str().ok())
-            .and_then(content_server::parse_range_header);
+        let range = match headers.get("range") {
+            None => None,
+            Some(value) => match value
+                .to_str()
+                .ok()
+                .and_then(content_server::parse_range_header)
+            {
+                Some(range) => Some(range),
+                None => {
+                    return Ok(build_response(
+                        StatusCode::BAD_REQUEST,
+                        "text/plain",
+                        hyper::Body::from("Invalid byte range"),
+                    ))
+                }
+            },
+        };
 
         match content_server::serve_content(
             &config.data_dir,
@@ -115,6 +209,7 @@ impl ApiHandler {
         )
         .await
         {
+            Ok(content_server::ServeResult::Stream(body)) => body.into_response(),
             Ok(content_server::ServeResult::Ok(bytes, mime_type)) => {
                 let len = bytes.len();
                 Ok(Response::builder()
@@ -162,18 +257,44 @@ impl ApiHandler {
                     r#"{"error":"This file is shared with the host's federation peers only. Federate with that node (exchange invites) so it recognizes you, then try again."}"#,
                 ),
             )),
-            Ok(content_server::ServeResult::NotFound) | Err(_) => Ok(build_response(
+            Ok(content_server::ServeResult::Unavailable) => Ok(build_response(
+                StatusCode::SERVICE_UNAVAILABLE,
+                "application/json",
+                hyper::Body::from(
+                    r#"{"error":"The seller's node can't read this file right now. This request did not redeem an ecash payment."}"#,
+                ),
+            )),
+            Ok(content_server::ServeResult::RangeNotSatisfiable(total)) => Ok(Response::builder()
+                .status(StatusCode::RANGE_NOT_SATISFIABLE)
+                .header("Content-Range", format!("bytes */{total}"))
+                .body(hyper::Body::empty())
+                .unwrap()),
+            Ok(content_server::ServeResult::NotFound) => Ok(build_response(
                 StatusCode::NOT_FOUND,
                 "text/plain",
                 hyper::Body::from("Content not found"),
             )),
+            // Not a 404: a paid request may already have been charged by the
+            // time this fails, and "not found" hid the real error entirely.
+            Err(e) => {
+                tracing::error!("Serving content {content_id} failed: {e:#}");
+                Ok(build_response(
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    "text/plain",
+                    hyper::Body::from("Failed to serve content"),
+                ))
+            }
         }
     }
 
     /// Seller side (#46): mint a Lightning invoice for a paid catalog item so a
     /// buyer can pay from any external wallet. Path: GET /content/{id}/invoice.
     /// Records a pending entitlement keyed by the invoice's payment hash.
-    pub(super) async fn handle_content_invoice(&self, path: &str) -> Result<Response<hyper::Body>> {
+    pub(super) async fn handle_content_invoice(
+        &self,
+        path: &str,
+        headers: &hyper::HeaderMap,
+    ) -> Result<Response<hyper::Body>> {
         let content_id = path
             .strip_prefix("/content/")
             .and_then(|s| s.strip_suffix("/invoice"))
@@ -186,6 +307,7 @@ impl ApiHandler {
             ));
         }
 
+        let (peer, known, owner) = self.content_access_context(path, headers).await?;
         let catalog = content_server::load_catalog(&self.config.data_dir)
             .await
             .unwrap_or_default();
@@ -199,6 +321,13 @@ impl ApiHandler {
                 ))
             }
         };
+        if !content_server::visible_to(item, peer.as_deref(), known, owner) {
+            return Ok(build_response(
+                StatusCode::NOT_FOUND,
+                "text/plain",
+                hyper::Body::from("Content not found"),
+            ));
+        }
         let price_sats = match &item.access {
             content_server::AccessControl::Paid { price_sats, .. } => *price_sats,
             _ => {
@@ -220,6 +349,18 @@ impl ApiHandler {
             ));
         }
 
+        if let Err(error) =
+            content_server::ensure_payment_source_available(&self.config.data_dir, item).await
+        {
+            return Ok(build_response(
+                StatusCode::CONFLICT,
+                "application/json",
+                hyper::Body::from(serde_json::to_vec(
+                    &serde_json::json!({ "error": error.to_string(), "payment_started": false }),
+                )?),
+            ));
+        }
+
         let memo = format!("Archipelago peer file {content_id}");
         match self
             .rpc_handler
@@ -227,7 +368,13 @@ impl ApiHandler {
             .await
         {
             Ok((bolt11, payment_hash)) if !payment_hash.is_empty() => {
-                crate::content_invoice::record_pending(&payment_hash, content_id, price_sats).await;
+                crate::content_invoice::record_pending(
+                    &self.config.data_dir,
+                    &payment_hash,
+                    content_id,
+                    price_sats,
+                )
+                .await?;
                 let body = serde_json::json!({
                     "bolt11": bolt11,
                     "payment_hash": payment_hash,
@@ -268,58 +415,20 @@ impl ApiHandler {
         &self,
         path: &str,
     ) -> Result<Response<hyper::Body>> {
-        let rest = path.strip_prefix("/content/").unwrap_or("");
-        let (content_id, payment_hash) = match rest.split_once("/invoice-status/") {
-            Some((id, hash)) => (id, hash),
-            None => {
-                return Ok(build_response(
-                    StatusCode::BAD_REQUEST,
-                    "text/plain",
-                    hyper::Body::from("Invalid request"),
-                ))
-            }
-        };
-        if content_id.is_empty() || !is_valid_app_id(content_id) || payment_hash.is_empty() {
-            return Ok(build_response(
-                StatusCode::BAD_REQUEST,
-                "text/plain",
-                hyper::Body::from("Invalid request"),
-            ));
-        }
-
-        // The hash must be one we issued for exactly this content item.
-        match crate::content_invoice::lookup(payment_hash).await {
-            Some((cid, _)) if cid == content_id => {}
-            _ => {
-                return Ok(build_response(
-                    StatusCode::NOT_FOUND,
-                    "application/json",
-                    hyper::Body::from(r#"{"error":"Unknown invoice"}"#),
-                ))
-            }
-        }
-
-        // Already paid? Otherwise ask our LND and persist the result.
-        let mut paid = crate::content_invoice::is_paid_for(payment_hash, content_id).await;
-        if !paid {
-            if let Ok(true) = self.rpc_handler.invoice_is_settled(payment_hash).await {
-                crate::content_invoice::mark_paid(payment_hash).await;
-                paid = true;
-            }
-        }
-
-        let body = serde_json::json!({ "paid": paid });
-        Ok(build_response(
-            StatusCode::OK,
-            "application/json",
-            hyper::Body::from(serde_json::to_vec(&body).unwrap_or_default()),
-        ))
+        Ok(invoice_status_response(path, |hash, id| async move {
+            self.rpc_handler.content_invoice_lifecycle(&hash, &id).await
+        })
+        .await)
     }
 
     /// Seller side (#46): issue a fresh on-chain address for a paid catalog item
     /// so a buyer can pay on-chain. Path: GET /content/{id}/onchain. Records a
     /// pending entitlement keyed by the address; price doubles as expected amount.
-    pub(super) async fn handle_content_onchain(&self, path: &str) -> Result<Response<hyper::Body>> {
+    pub(super) async fn handle_content_onchain(
+        &self,
+        path: &str,
+        headers: &hyper::HeaderMap,
+    ) -> Result<Response<hyper::Body>> {
         let content_id = path
             .strip_prefix("/content/")
             .and_then(|s| s.strip_suffix("/onchain"))
@@ -331,13 +440,27 @@ impl ApiHandler {
                 hyper::Body::from("Invalid content ID"),
             ));
         }
+        let (peer, known, owner) = self.content_access_context(path, headers).await?;
         let catalog = content_server::load_catalog(&self.config.data_dir)
             .await
             .unwrap_or_default();
-        let price_sats = match catalog.items.iter().find(|i| i.id == content_id) {
-            Some(i) => match &i.access {
+        let Some(item) = catalog.items.iter().find(|item| item.id == content_id) else {
+            return Ok(build_response(
+                StatusCode::NOT_FOUND,
+                "text/plain",
+                hyper::Body::from("Content not found"),
+            ));
+        };
+        if !content_server::visible_to(item, peer.as_deref(), known, owner) {
+            return Ok(build_response(
+                StatusCode::NOT_FOUND,
+                "text/plain",
+                hyper::Body::from("Content not found"),
+            ));
+        }
+        let price_sats = match &item.access {
             content_server::AccessControl::Paid { price_sats, .. } => {
-                    if !content_server::method_accepted(&i.access, "onchain") {
+                if !content_server::method_accepted(&item.access, "onchain") {
                     return Ok(build_response(
                         StatusCode::BAD_REQUEST,
                         "application/json",
@@ -355,19 +478,42 @@ impl ApiHandler {
                     hyper::Body::from(r#"{"error":"Item is not paid"}"#),
                 ))
             }
-            },
-            None => {
-                return Ok(build_response(
-                    StatusCode::NOT_FOUND,
-                    "text/plain",
-                    hyper::Body::from("Content not found"),
-                ))
-            }
         };
 
+        // Match the node wallet's existing sendcoins minimum before exposing a
+        // payable address for an amount its own payment flow cannot broadcast.
+        if let Err(error) = content_server::validate_onchain_payment_price(price_sats) {
+            return Ok(build_response(
+                StatusCode::BAD_REQUEST,
+                "application/json",
+                hyper::Body::from(serde_json::to_vec(
+                    &serde_json::json!({ "error": error.to_string(), "payment_started": false }),
+                )?),
+            ));
+        }
+
+        if let Err(error) =
+            content_server::ensure_payment_source_available(&self.config.data_dir, item).await
+        {
+            return Ok(build_response(
+                StatusCode::CONFLICT,
+                "application/json",
+                hyper::Body::from(serde_json::to_vec(
+                    &serde_json::json!({ "error": error.to_string(), "payment_started": false }),
+                )?),
+            ));
+        }
+
         match self.rpc_handler.new_onchain_address().await {
             Ok(address) if !address.is_empty() => {
-                crate::content_invoice::record_pending(&address, content_id, price_sats).await;
+                crate::content_invoice::record_pending_method(
+                    &self.config.data_dir,
+                    &address,
+                    content_id,
+                    price_sats,
+                    crate::content_invoice::PaymentMethod::Onchain,
+                )
+                .await?;
                 let body = serde_json::json!({
                     "address": address,
                     "amount_sats": price_sats,
@@ -417,7 +563,7 @@ impl ApiHandler {
             ));
         }
         // The address must be one we issued for exactly this content item.
-        let price = match crate::content_invoice::lookup(address).await {
+        let price = match crate::content_invoice::lookup(&self.config.data_dir, address).await? {
             Some((cid, price)) if cid == content_id => price,
             _ => {
                 return Ok(build_response(
@@ -428,12 +574,25 @@ impl ApiHandler {
             }
         };
 
-        let mut paid = crate::content_invoice::is_paid_for(address, content_id).await;
+        let mut paid =
+            crate::content_invoice::is_paid_for(&self.config.data_dir, address, content_id).await;
         if !paid {
-            if let Ok(true) = self.rpc_handler.onchain_received(address, price).await {
-                crate::content_invoice::mark_paid(address).await;
+            match self.rpc_handler.onchain_received(address, price).await {
+                Ok(true) => {
+                    crate::content_invoice::mark_paid(&self.config.data_dir, address).await?;
                     paid = true;
                 }
+                Ok(false) => {}
+                Err(_) => return Ok(build_response(
+                    StatusCode::OK,
+                    "application/json",
+                    hyper::Body::from(serde_json::to_vec(&serde_json::json!({
+                        "paid": false,
+                        "status": "unknown",
+                        "error": "Exact on-chain outputs could not be verified. Keep the original payment address and do not pay again."
+                    }))?),
+                )),
+            }
         }
         let body = serde_json::json!({ "paid": paid });
         Ok(build_response(
@@ -463,6 +622,7 @@ impl ApiHandler {
         }
 
         match content_server::serve_content_preview(&config.data_dir, content_id).await {
+            Ok(content_server::PreviewResult::Stream(body)) => body.into_response(),
             Ok(content_server::PreviewResult::FullContent(bytes, mime_type)) => {
                 let len = bytes.len();
                 Ok(Response::builder()
@@ -509,3 +669,109 @@ impl ApiHandler {
         }
     }
 }
+
+/// Keep invalid input and an unavailable wallet inside the HTTP protocol so
+/// buyers can retry delivery without treating a dropped socket as lost payment.
+async fn invoice_status_response<F, Fut>(path: &str, settle: F) -> Response<hyper::Body>
+where
+    F: FnOnce(String, String) -> Fut,
+    Fut: std::future::Future<Output = Result<serde_json::Value>>,
+{
+    let parsed = path
+        .strip_prefix("/content/")
+        .and_then(|rest| rest.split_once("/invoice-status/"))
+        .filter(|(id, hash)| {
+            !id.is_empty()
+                && is_valid_app_id(id)
+                && hash.len() == 64
+                && hash.bytes().all(|c| c.is_ascii_hexdigit())
+        });
+    let Some((id, hash)) = parsed else {
+        return build_response(
+            StatusCode::BAD_REQUEST,
+            "application/json",
+            hyper::Body::from(r#"{"error":"Invalid content ID or payment hash"}"#),
+        );
+    };
+    match settle(hash.to_ascii_lowercase(), id.to_owned()).await {
+        Ok(body) => build_response(
+            StatusCode::OK,
+            "application/json",
+            hyper::Body::from(body.to_string()),
+        ),
+        Err(_) => {
+            tracing::warn!("Peer-file payment status verification is temporarily unavailable");
+            let mut response = build_response(
+                StatusCode::SERVICE_UNAVAILABLE,
+                "application/json",
+                hyper::Body::from(
+                    r#"{"error":"Payment verification is temporarily unavailable. Retry without paying again."}"#,
+                ),
+            );
+            response.headers_mut().insert(
+                hyper::header::RETRY_AFTER,
+                hyper::header::HeaderValue::from_static("5"),
+            );
+            response
+        }
+    }
+}
+
+#[cfg(test)]
+mod invoice_status_tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn malformed_requests_do_not_query_the_wallet() {
+        for path in [
+            "/bad",
+            "/content//invoice-status/aa",
+            "/content/file/invoice-status/aa",
+            "/content/file/invoice-status/",
+            "/content/file/invoice-status/not-a-hash",
+        ] {
+            let response = invoice_status_response(path, |_, _| async {
+                panic!("Invalid request reached wallet");
+                #[allow(unreachable_code)]
+                Ok(serde_json::json!({"paid":false}))
+            })
+            .await;
+            assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+            assert_eq!(response.headers()["content-type"], "application/json");
+            let body = hyper::body::to_bytes(response.into_body()).await.unwrap();
+            assert!(
+                serde_json::from_slice::<serde_json::Value>(&body).unwrap()["error"].is_string()
+            );
+        }
+    }
+
+    #[tokio::test]
+    async fn settlement_results_and_failures_have_explicit_http_responses() {
+        let hash = "AB".repeat(32);
+        let path = format!("/content/file/invoice-status/{hash}");
+        for paid in [false, true] {
+            let response = invoice_status_response(&path, |hash, id| async move {
+                assert_eq!(hash, "ab".repeat(32));
+                assert_eq!(id, "file");
+                Ok(serde_json::json!({"paid":paid}))
+            })
+            .await;
+            assert_eq!(response.status(), StatusCode::OK);
+            let body = hyper::body::to_bytes(response.into_body()).await.unwrap();
+            assert_eq!(
+                serde_json::from_slice::<serde_json::Value>(&body).unwrap()["paid"],
+                paid
+            );
+        }
+        let response = invoice_status_response(&path, |_, _| async {
+            anyhow::bail!("private wallet details must not escape")
+        })
+        .await;
+        assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
+        assert_eq!(response.headers()["retry-after"], "5");
+        let body = hyper::body::to_bytes(response.into_body()).await.unwrap();
+        let text = String::from_utf8(body.to_vec()).unwrap();
+        assert!(text.contains("without paying again"));
+        assert!(!text.contains("private wallet"));
+    }
+}

core/archipelago/src/api/handler/lightning_purchase.rs

@@ -0,0 +1,241 @@
+use super::{build_response, ApiHandler};
+use crate::content_lightning::{Binding, Journal, Phase};
+use anyhow::{Context, Result};
+use hyper::{body::HttpBody, Body, Method, Request, Response, StatusCode};
+use serde::{Deserialize, Serialize};
+use tokio::io::AsyncReadExt;
+pub(crate) const ROUTE: &str = "/content/lightning/v1/operation";
+#[derive(Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct Operation {
+    pub binding: Binding,
+    pub action: String,
+}
+impl ApiHandler {
+    pub(super) async fn handle_lightning_purchase(
+        &self,
+        mut request: Request<Body>,
+    ) -> Result<Response<Body>> {
+        anyhow::ensure!(
+            request.method() == Method::POST && request.uri().path() == ROUTE,
+            "Invalid invoice route"
+        );
+        let bytes = tokio::time::timeout(std::time::Duration::from_secs(15), async {
+            let mut bytes = Vec::new();
+            while let Some(chunk) = request.body_mut().data().await {
+                let chunk = chunk?;
+                anyhow::ensure!(
+                    bytes.len() + chunk.len() <= 16384,
+                    "Invoice request too large"
+                );
+                bytes.extend_from_slice(&chunk)
+            }
+            Ok::<_, anyhow::Error>(bytes)
+        })
+        .await
+        .context("Invoice request timed out")??;
+        let seller = crate::identity::did_key_from_pubkey_hex(&self.self_pubkey_hex)?;
+        let buyer = crate::content_auth::authenticate_request(
+            request.headers(),
+            &seller,
+            &Method::POST,
+            ROUTE,
+            &bytes,
+            chrono::Utc::now().timestamp(),
+        )?;
+        let operation: Operation = serde_json::from_slice(&bytes)?;
+        anyhow::ensure!(
+            operation.binding.buyer_did == buyer && operation.binding.seller_did == seller,
+            "Invoice peer identity mismatch"
+        );
+        anyhow::ensure!(
+            matches!(
+                operation.action.as_str(),
+                "create" | "status" | "cancel" | "download"
+            ),
+            "Invalid invoice action"
+        );
+        let binding = &operation.binding;
+        let journal = Journal::open(&self.config.data_dir).await?;
+        let mut saved = journal.seller(binding)?;
+        if saved.is_none() {
+            anyhow::ensure!(
+                operation.action == "create",
+                "Unknown original invoice operation"
+            );
+            anyhow::ensure!(
+                !binding.content_id.starts_with("registered_"),
+                "Registered rentals use their native purchase contract"
+            );
+            let catalog = crate::content_server::load_catalog(&self.config.data_dir).await?;
+            let item = catalog
+                .items
+                .iter()
+                .find(|v| v.id == binding.content_id)
+                .context("Shared item unavailable")?;
+            let visible = match &item.availability {
+                crate::content_server::Availability::Nobody => false,
+                crate::content_server::Availability::AllPeers => true,
+                crate::content_server::Availability::Specific { peers } => peers.contains(&buyer),
+            };
+            anyhow::ensure!(visible, "Item is not shared with this buyer");
+            anyhow::ensure!(
+                matches!(&item.access,crate::content_server::AccessControl::Paid{price_sats,..} if *price_sats==binding.price_sats)
+                    && crate::content_server::method_accepted(&item.access, "lightning"),
+                "Invoice price or accepted method changed"
+            );
+            crate::content_server::ensure_payment_source_available(&self.config.data_dir, item)
+                .await?;
+            let source = crate::content_server::content_file_path(&self.config.data_dir, item);
+            let roots = [
+                self.config.data_dir.join("content/files"),
+                self.config.data_dir.join("filebrowser"),
+            ];
+            let (root, relative) = roots
+                .iter()
+                .find_map(|root| {
+                    source
+                        .strip_prefix(root)
+                        .ok()
+                        .map(|p| (root.clone(), p.to_path_buf()))
+                })
+                .context("Unsupported invoice source root")?;
+            let data = self.config.data_dir.clone();
+            let id = binding.content_id.clone();
+            struct CancelCopy(std::sync::Arc<std::sync::atomic::AtomicBool>);
+            impl Drop for CancelCopy {
+                fn drop(&mut self) {
+                    self.0.store(true, std::sync::atomic::Ordering::SeqCst);
+                }
+            }
+            let cancel_copy = CancelCopy(std::sync::Arc::new(std::sync::atomic::AtomicBool::new(
+                false,
+            )));
+            let cancelled = cancel_copy.0.clone();
+            let snapshot = tokio::task::spawn_blocking(move || {
+                crate::content_snapshot::prepare(
+                    &data,
+                    &root,
+                    &id,
+                    &relative,
+                    &crate::media_registration::Limits {
+                        max_bytes: 64 * 1024 * 1024 * 1024,
+                        cancelled: &cancelled,
+                    },
+                    64 * 1024 * 1024 * 1024,
+                    512 * 1024 * 1024,
+                    |_| Ok(()),
+                )
+            })
+            .await??;
+            anyhow::ensure!(
+                snapshot.size == item.size_bytes,
+                "Shared file changed before invoice"
+            );
+            // Source metadata is private and committed before AddInvoice dispatch.
+            let record = crate::content_server::publish_snapshot_invoice(
+                &self.config.data_dir,
+                item,
+                &journal,
+                binding.clone(),
+                crate::content_lightning::RetainedFile {
+                    sha256: snapshot.sha256,
+                    size: snapshot.size,
+                    filename: item.filename.clone(),
+                    mime_type: item.mime_type.clone(),
+                },
+            )
+            .await?;
+            saved = Some(record);
+        }
+        let mut saved = saved.context("Missing invoice operation")?;
+        anyhow::ensure!(
+            saved.source.is_some(),
+            "Original invoice source is not prepared; no new invoice dispatched"
+        );
+        let status = if operation.action == "cancel" && saved.phase == Phase::Prepared {
+            saved.phase = Phase::CanceledUnpaid;
+            journal.save_seller(&saved)?;
+            saved.status()
+        } else if operation.action != "create"
+            && operation.action != "cancel"
+            && saved.phase == Phase::Prepared
+        {
+            saved.status()
+        } else {
+            self.rpc_handler
+                .drive_external_invoice(&journal, binding, operation.action == "cancel")
+                .await?
+        };
+        // The original legacy delivery mechanism remains usable by its hash.
+        if status.bolt11.is_some() {
+            crate::content_invoice::record_pending(
+                &self.config.data_dir,
+                &status.payment_hash,
+                &binding.content_id,
+                binding.price_sats,
+            )
+            .await?;
+            if status.state == Phase::Settled {
+                crate::content_invoice::mark_paid(&self.config.data_dir, &status.payment_hash)
+                    .await?;
+            }
+        }
+        if operation.action == "download" {
+            anyhow::ensure!(
+                status.state == Phase::Settled,
+                "Original invoice has not settled"
+            );
+            let source = status
+                .source
+                .as_ref()
+                .context("Original invoice snapshot is missing")?;
+            let data = self.config.data_dir.clone();
+            let id = binding.content_id.clone();
+            let retained = source.clone();
+            struct CancelCopy(std::sync::Arc<std::sync::atomic::AtomicBool>);
+            impl Drop for CancelCopy {
+                fn drop(&mut self) {
+                    self.0.store(true, std::sync::atomic::Ordering::SeqCst);
+                }
+            }
+            let cancel_copy = CancelCopy(std::sync::Arc::new(std::sync::atomic::AtomicBool::new(
+                false,
+            )));
+            let cancelled = cancel_copy.0.clone();
+            let snapshot = tokio::task::spawn_blocking(move || {
+                crate::content_snapshot::open_matching(&data, &id, &retained.sha256, retained.size)
+            })
+            .await??;
+            let stream = futures_util::stream::try_unfold(
+                (tokio::fs::File::from_std(snapshot.file), source.size),
+                |(mut file, left)| async move {
+                    if left == 0 {
+                        return Ok::<_, std::io::Error>(None);
+                    }
+                    let mut bytes = vec![0; left.min(65536) as usize];
+                    let count = file.read(&mut bytes).await?;
+                    if count == 0 {
+                        return Err(std::io::Error::new(
+                            std::io::ErrorKind::UnexpectedEof,
+                            "Original invoice snapshot ended early",
+                        ));
+                    }
+                    bytes.truncate(count);
+                    Ok(Some((bytes, (file, left - count as u64))))
+                },
+            );
+            return Ok(Response::builder()
+                .status(StatusCode::OK)
+                .header("Content-Type", &source.mime_type)
+                .header("Content-Length", source.size)
+                .header("Cache-Control", "private, no-store")
+                .body(Body::wrap_stream(stream))?);
+        }
+        Ok(build_response(
+            StatusCode::OK,
+            "application/json",
+            Body::from(serde_json::to_vec(&status)?),
+        ))
+    }
+}

core/archipelago/src/api/handler/mod.rs

@@ -1,12 +1,18 @@
 mod blob;
 mod cdp;
+mod cloud_purchase;
 mod content;
 mod dwn;
+pub(crate) mod lightning_purchase;
 mod model_proxy;
 mod node_message;
+pub(crate) mod onchain_purchase;
 mod proxy;
+mod purchase;
+mod registered_media;
 mod remote_input;
 mod remote_relay;
+mod rental_playback;
 mod routstr_proxy;
 mod websocket;
 
@@ -384,6 +390,12 @@ impl ApiHandler {
         let path = req.uri().path().to_string();
         let method = req.method().clone();
 
+        if path.starts_with("/api/rental-playback/") {
+            return self
+                .handle_local_rental_request(&method, &path, req.headers())
+                .await;
+        }
+
         // Handle CORS preflight for all routes
         if method == Method::OPTIONS {
             let mut builder = Response::builder()
@@ -444,6 +456,32 @@ impl ApiHandler {
             .await;
         }
 
+        if method == Method::POST && path == lightning_purchase::ROUTE {
+            return self.handle_lightning_purchase(req).await;
+        }
+        // Purchase routes bound the original body before the generic buffer.
+        if method == Method::POST
+            && matches!(
+                path.as_str(),
+                crate::content_purchase_protocol::PREPARE_OFFER_ROUTE
+                    | crate::content_purchase_protocol::OFFER_ROUTE
+                    | crate::content_purchase_protocol::ACCEPT_ROUTE
+                    | crate::content_purchase_protocol::SETTLE_ROUTE
+                    | crate::content_purchase_protocol::STATUS_ROUTE
+                    | crate::content_purchase_protocol::CANCEL_ROUTE
+            )
+        {
+            return self.handle_purchase_request(req).await;
+        }
+
+        if method == Method::POST
+            && path.starts_with("/content/registered_")
+            && path.contains("/rental/")
+            && (path.ends_with("/prepare") || path.ends_with("/start"))
+        {
+            return self.handle_rental_control(req).await;
+        }
+
         // Convert body to bytes for non-WS routes
         let headers = req.headers().clone();
         let query_string = req.uri().query().map(|s| s.to_string()).unwrap_or_default();
@@ -584,6 +622,15 @@ impl ApiHandler {
                 Self::handle_blob_download(&self.blob_store, p, &query_string).await
             }
 
+            // Immutable registered rentals use durable seller receipts and their
+            // first-open window, never legacy mutable filename shares.
+            (Method::GET, p) if p.starts_with("/content/") && p.contains("/purchase/") => {
+                self.handle_cloud_purchase(p, &headers).await
+            }
+            (Method::GET, p) if p.starts_with("/content/registered_") && p.contains("/rental/") => {
+                self.handle_registered_rental(p, &headers).await
+            }
+
             // Content preview — degraded previews for paid content (no auth, no payment)
             (Method::GET, p) if p.starts_with("/content/") && p.ends_with("/preview") => {
                 Self::handle_content_preview(p, &self.config).await
@@ -591,7 +638,7 @@ impl ApiHandler {
 
             // Lightning-invoice peer-file sale (#46): mint invoice / poll settlement
             (Method::GET, p) if p.starts_with("/content/") && p.ends_with("/invoice") => {
-                self.handle_content_invoice(p).await
+                self.handle_content_invoice(p, &headers).await
             }
             (Method::GET, p) if p.starts_with("/content/") && p.contains("/invoice-status/") => {
                 self.handle_content_invoice_status(p).await
@@ -602,7 +649,7 @@ impl ApiHandler {
                 self.handle_content_onchain_status(p).await
             }
             (Method::GET, p) if p.starts_with("/content/") && p.ends_with("/onchain") => {
-                self.handle_content_onchain(p).await
+                self.handle_content_onchain(p, &headers).await
             }
 
             // Content serving — peers access shared content over Tor (no session auth);
@@ -612,7 +659,7 @@ impl ApiHandler {
             }
 
             // Content catalog — list available content (no session auth, for peers)
-            (Method::GET, "/content") => Self::handle_content_catalog(&self.config).await,
+            (Method::GET, "/content") => self.handle_content_catalog(&headers).await,
 
             // Electrs status — unauthenticated (read-only sync status)
             (Method::GET, "/electrs-status") => Self::handle_electrs_status().await,
@@ -623,6 +670,34 @@ impl ApiHandler {
             // (upstream Gitea has no ACAO header) or CSP (IP-port upstream
             // falls outside `connect-src`). Session-authenticated so only
             // the logged-in node owner can spin up fetches.
+            (Method::GET, "/api/node-app-catalog") => {
+                if !self.is_authenticated(&headers).await {
+                    return Ok(Self::unauthorized());
+                }
+                let data_dir = self.config.data_dir.clone();
+                let result = tokio::task::spawn_blocking(move || {
+                    crate::container::node_catalog::verified_body(&data_dir)
+                })
+                .await
+                .unwrap_or_else(|error| Err(anyhow::anyhow!(error)));
+                let (status, body) = match result {
+                    Ok(Some(body)) => (StatusCode::OK, body),
+                    Ok(None) => (StatusCode::NOT_FOUND, "{}".to_owned()),
+                    Err(error) => {
+                        tracing::warn!("Node demo catalog rejected: {error}");
+                        (
+                            StatusCode::CONFLICT,
+                            "{\"error\":\"Node demo catalog is unavailable\"}".to_owned(),
+                        )
+                    }
+                };
+                Ok(Response::builder()
+                    .status(status)
+                    .header("Content-Type", "application/json")
+                    .header("Cache-Control", "private, no-store")
+                    .body(hyper::Body::from(body))?)
+            }
+
             (Method::GET, "/api/app-catalog") => {
                 if !self.is_authenticated(&headers).await {
                     return Ok(Self::unauthorized());

core/archipelago/src/api/handler/onchain_purchase.rs

@@ -0,0 +1,712 @@
+use super::{build_response, ApiHandler};
+use crate::{content_lightning::Binding, content_onchain_seller::Journal};
+use anyhow::{Context, Result};
+use hyper::{body::HttpBody, Body, Method, Request, Response, StatusCode};
+use serde::{Deserialize, Serialize};
+use tokio::io::AsyncReadExt;
+pub(crate) const ROUTE: &str = "/content/onchain/v1/operation";
+#[derive(Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct Operation {
+    pub binding: Binding,
+    pub action: String,
+}
+// Load wallet credentials only after authenticated request validation reaches a
+// wallet operation. Tests inject the same typed boundary without live services.
+struct NativeSellerWallet<'a>(&'a crate::api::rpc::RpcHandler);
+impl crate::content_onchain_seller::Wallet for NativeSellerWallet<'_> {
+    async fn network(&self) -> Result<crate::content_onchain::ChainNetwork> {
+        self.0.onchain_purchase_wallet().await?.network().await
+    }
+    async fn preflight(&self, network: crate::content_onchain::ChainNetwork) -> Result<()> {
+        self.0
+            .onchain_purchase_wallet()
+            .await?
+            .preflight(network)
+            .await
+    }
+    async fn allocate(&self) -> Result<String> {
+        self.0.onchain_purchase_wallet().await?.allocate().await
+    }
+    async fn received(&self, address: &str, amount: u64) -> Result<bool> {
+        self.0
+            .onchain_purchase_wallet()
+            .await?
+            .received(address, amount)
+            .await
+    }
+}
+impl ApiHandler {
+    pub(super) async fn handle_onchain_purchase(
+        &self,
+        request: Request<Body>,
+    ) -> Result<Response<Body>> {
+        self.handle_onchain_purchase_with_wallet(request, &NativeSellerWallet(&self.rpc_handler))
+            .await
+    }
+    async fn handle_onchain_purchase_with_wallet<W: crate::content_onchain_seller::Wallet>(
+        &self,
+        mut request: Request<Body>,
+        wallet: &W,
+    ) -> Result<Response<Body>> {
+        anyhow::ensure!(
+            request.method() == Method::POST && request.uri().path() == ROUTE,
+            "Invalid on-chain purchase route"
+        );
+        let bytes = tokio::time::timeout(std::time::Duration::from_secs(15), async {
+            let mut bytes = Vec::new();
+            while let Some(chunk) = request.body_mut().data().await {
+                let chunk = chunk?;
+                anyhow::ensure!(
+                    bytes.len() + chunk.len() <= 16384,
+                    "On-chain purchase request too large"
+                );
+                bytes.extend_from_slice(&chunk)
+            }
+            Ok::<_, anyhow::Error>(bytes)
+        })
+        .await
+        .context("On-chain purchase request timed out")??;
+        let seller = crate::identity::did_key_from_pubkey_hex(&self.self_pubkey_hex)?;
+        let buyer = crate::content_auth::authenticate_request(
+            request.headers(),
+            &seller,
+            &Method::POST,
+            ROUTE,
+            &bytes,
+            chrono::Utc::now().timestamp(),
+        )?;
+        let operation: Operation = serde_json::from_slice(&bytes)?;
+        anyhow::ensure!(
+            operation.binding.buyer_did == buyer && operation.binding.seller_did == seller,
+            "On-chain purchase peer identity mismatch"
+        );
+        anyhow::ensure!(
+            matches!(
+                operation.action.as_str(),
+                "create" | "offer" | "allocate" | "status" | "download" | "cancel"
+            ),
+            "Invalid on-chain purchase action"
+        );
+        let binding = &operation.binding;
+        let journal = Journal::open(&self.config.data_dir).await?;
+        let retired = if operation.action == "cancel" {
+            Some(journal.retire_unallocated(binding)?)
+        } else {
+            journal.retirement(binding)?
+        };
+        if let Some(ack) = retired {
+            return Ok(build_response(
+                StatusCode::OK,
+                "application/json",
+                Body::from(serde_json::to_vec(&ack)?),
+            ));
+        }
+        let mut saved = journal.load(binding)?;
+        if saved.is_none() {
+            anyhow::ensure!(
+                matches!(operation.action.as_str(), "create" | "offer"),
+                "Unknown original on-chain purchase operation"
+            );
+            anyhow::ensure!(
+                !binding.content_id.starts_with("registered_"),
+                "Registered rentals use their native purchase contract"
+            );
+            let catalog = crate::content_server::load_catalog(&self.config.data_dir).await?;
+            let item = catalog
+                .items
+                .iter()
+                .find(|v| v.id == binding.content_id)
+                .context("Shared item unavailable")?;
+            let visible = match &item.availability {
+                crate::content_server::Availability::Nobody => false,
+                crate::content_server::Availability::AllPeers => true,
+                crate::content_server::Availability::Specific { peers } => peers.contains(&buyer),
+            };
+            anyhow::ensure!(visible, "Item is not shared with this buyer");
+            anyhow::ensure!(
+                matches!(&item.access,crate::content_server::AccessControl::Paid{price_sats,..} if *price_sats==binding.price_sats)
+                    && crate::content_server::method_accepted(&item.access, "onchain"),
+                "On-chain purchase price or accepted method changed"
+            );
+            crate::content_server::ensure_payment_source_available(&self.config.data_dir, item)
+                .await?;
+            let source = crate::content_server::content_file_path(&self.config.data_dir, item);
+            let roots = [
+                self.config.data_dir.join("content/files"),
+                self.config.data_dir.join("filebrowser"),
+            ];
+            let (root, relative) = roots
+                .iter()
+                .find_map(|root| {
+                    source
+                        .strip_prefix(root)
+                        .ok()
+                        .map(|p| (root.clone(), p.to_path_buf()))
+                })
+                .context("Unsupported on-chain purchase source root")?;
+            let data = self.config.data_dir.clone();
+            let id = binding.content_id.clone();
+            struct CancelCopy(std::sync::Arc<std::sync::atomic::AtomicBool>);
+            impl Drop for CancelCopy {
+                fn drop(&mut self) {
+                    self.0.store(true, std::sync::atomic::Ordering::SeqCst);
+                }
+            }
+            let cancel_copy = CancelCopy(std::sync::Arc::new(std::sync::atomic::AtomicBool::new(
+                false,
+            )));
+            let cancelled = cancel_copy.0.clone();
+            let snapshot = tokio::task::spawn_blocking(move || {
+                crate::content_snapshot::prepare(
+                    &data,
+                    &root,
+                    &id,
+                    &relative,
+                    &crate::media_registration::Limits {
+                        max_bytes: 64 * 1024 * 1024 * 1024,
+                        cancelled: &cancelled,
+                    },
+                    64 * 1024 * 1024 * 1024,
+                    512 * 1024 * 1024,
+                    |_| Ok(()),
+                )
+            })
+            .await??;
+            anyhow::ensure!(
+                snapshot.size == item.size_bytes,
+                "Shared file changed before on-chain purchase"
+            );
+            // Source metadata is private and committed before address allocation.
+            let record = crate::content_server::publish_snapshot_onchain(
+                &self.config.data_dir,
+                item,
+                &journal,
+                binding.clone(),
+                crate::content_lightning::RetainedFile {
+                    sha256: snapshot.sha256,
+                    size: snapshot.size,
+                    filename: item.filename.clone(),
+                    mime_type: item.mime_type.clone(),
+                },
+                wallet.network().await?,
+            )
+            .await?;
+            saved = Some(record);
+        }
+        saved.context("Missing original on-chain operation")?;
+        let status = if operation.action == "allocate" {
+            crate::content_server::allocate_onchain_offer(
+                &self.config.data_dir,
+                &journal,
+                binding,
+                wallet,
+            )
+            .await?
+        } else {
+            crate::content_onchain_seller::drive(&journal, binding, false, wallet).await?
+        };
+        if operation.action == "download" {
+            anyhow::ensure!(status.paid, "Original on-chain purchase has not settled");
+            let source = &status.source;
+            let data = self.config.data_dir.clone();
+            let id = binding.content_id.clone();
+            let retained = source.clone();
+            let snapshot = tokio::task::spawn_blocking(move || {
+                crate::content_snapshot::open_matching(&data, &id, &retained.sha256, retained.size)
+            })
+            .await??;
+            let stream = futures_util::stream::try_unfold(
+                (tokio::fs::File::from_std(snapshot.file), source.size),
+                |(mut file, left)| async move {
+                    if left == 0 {
+                        return Ok::<_, std::io::Error>(None);
+                    }
+                    let mut bytes = vec![0; left.min(65536) as usize];
+                    let count = file.read(&mut bytes).await?;
+                    if count == 0 {
+                        return Err(std::io::Error::new(
+                            std::io::ErrorKind::UnexpectedEof,
+                            "Original on-chain purchase snapshot ended early",
+                        ));
+                    }
+                    bytes.truncate(count);
+                    Ok(Some((bytes, (file, left - count as u64))))
+                },
+            );
+            return Ok(Response::builder()
+                .status(StatusCode::OK)
+                .header("Content-Type", &source.mime_type)
+                .header("Content-Length", source.size)
+                .header("Cache-Control", "private, no-store")
+                .body(Body::wrap_stream(stream))?);
+        }
+        Ok(build_response(
+            StatusCode::OK,
+            "application/json",
+            Body::from(serde_json::to_vec(&status)?),
+        ))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::content_onchain_seller::{Allocation, UnallocatedAck};
+    use hyper::service::{make_service_fn, service_fn};
+    use std::{convert::Infallible, sync::Arc};
+    #[derive(Default)]
+    struct MockWallet {
+        allocations: std::sync::atomic::AtomicUsize,
+        lose_reply: std::sync::atomic::AtomicBool,
+    }
+    impl crate::content_onchain_seller::Wallet for MockWallet {
+        async fn network(&self) -> Result<crate::content_onchain::ChainNetwork> {
+            Ok(crate::content_onchain::ChainNetwork::Regtest)
+        }
+        async fn preflight(&self, _: crate::content_onchain::ChainNetwork) -> Result<()> {
+            Ok(())
+        }
+        async fn allocate(&self) -> Result<String> {
+            self.allocations
+                .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+            anyhow::ensure!(
+                !self
+                    .lose_reply
+                    .swap(false, std::sync::atomic::Ordering::SeqCst),
+                "Simulated lost allocation response"
+            );
+            let mut bytes = vec![0, 20];
+            bytes.extend([17u8; 20]);
+            Ok(bitcoin::Address::from_script(
+                &bitcoin::ScriptBuf::from_bytes(bytes),
+                bitcoin::Network::Regtest,
+            )?
+            .to_string())
+        }
+        async fn received(&self, _: &str, _: u64) -> Result<bool> {
+            Ok(false)
+        }
+    }
+    struct HttpFixture {
+        wallet: Arc<MockWallet>,
+        data: tempfile::TempDir,
+        _buyer_data: tempfile::TempDir,
+        buyer: crate::identity::NodeIdentity,
+        seller: String,
+        url: String,
+        task: tokio::task::JoinHandle<()>,
+    }
+    impl Drop for HttpFixture {
+        fn drop(&mut self) {
+            self.task.abort();
+        }
+    }
+    async fn fixture() -> HttpFixture {
+        let data = tempfile::tempdir().unwrap();
+        let buyer_data = tempfile::tempdir().unwrap();
+        let buyer = crate::identity::NodeIdentity::load_or_create(buyer_data.path())
+            .await
+            .unwrap();
+        let mut config = crate::config::Config::default();
+        config.data_dir = data.path().to_path_buf();
+        let handler = Arc::new(
+            ApiHandler::new(
+                config,
+                Arc::new(crate::state::StateManager::new()),
+                Arc::new(crate::monitoring::MetricsStore::new()),
+                None,
+                None,
+            )
+            .await
+            .unwrap(),
+        );
+        let seller = crate::identity::did_key_from_pubkey_hex(&handler.self_pubkey_hex).unwrap();
+        let wallet = Arc::new(MockWallet::default());
+        let server_wallet = wallet.clone();
+        let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
+        listener.set_nonblocking(true).unwrap();
+        let url = format!("http://{}", listener.local_addr().unwrap());
+        let server = hyper::Server::from_tcp(listener)
+            .unwrap()
+            .serve(make_service_fn(move |_| {
+                let handler = handler.clone();
+                let wallet = server_wallet.clone();
+                async move {
+                    Ok::<_, Infallible>(service_fn(move |request| {
+                        let handler = handler.clone();
+                        let wallet = wallet.clone();
+                        async move {
+                            Ok::<_, Infallible>(
+                                handler
+                                    .handle_onchain_purchase_with_wallet(request, wallet.as_ref())
+                                    .await
+                                    .unwrap_or_else(|_| {
+                                        build_response(
+                                            StatusCode::BAD_REQUEST,
+                                            "application/json",
+                                            Body::from("{\"error\":\"rejected\"}"),
+                                        )
+                                    }),
+                            )
+                        }
+                    }))
+                }
+            }));
+        let task = tokio::spawn(async move {
+            server.await.unwrap();
+        });
+        HttpFixture {
+            wallet,
+            data,
+            _buyer_data: buyer_data,
+            buyer,
+            seller,
+            url,
+            task,
+        }
+    }
+    impl HttpFixture {
+        fn binding(&self) -> Binding {
+            Binding {
+                id: uuid::Uuid::new_v4().to_string(),
+                buyer_did: self.buyer.did_key().unwrap(),
+                seller_did: self.seller.clone(),
+                content_id: "file".into(),
+                price_sats: 546,
+            }
+        }
+        async fn send(
+            &self,
+            body: &[u8],
+            signed_body: Option<&[u8]>,
+            audience: Option<&str>,
+        ) -> reqwest::Response {
+            let mut request = reqwest::Client::new()
+                .post(format!("{}{}", self.url, ROUTE))
+                .header("content-type", "application/json")
+                .body(body.to_vec());
+            if let Some(signed) = signed_body {
+                let proof = crate::content_auth::sign_request(
+                    &self.buyer,
+                    audience.unwrap_or(&self.seller),
+                    &Method::POST,
+                    ROUTE,
+                    signed,
+                    chrono::Utc::now().timestamp(),
+                )
+                .unwrap();
+                request = request.header(crate::content_auth::REQUEST_HEADER, proof);
+            }
+            request.send().await.unwrap()
+        }
+        async fn operation(&self, binding: &Binding, action: &str) -> reqwest::Response {
+            let body = serde_json::to_vec(&Operation {
+                binding: binding.clone(),
+                action: action.into(),
+            })
+            .unwrap();
+            self.send(&body, Some(&body), None).await
+        }
+    }
+    #[tokio::test]
+    async fn authenticated_cancel_roundtrip_lost_reply_and_delayed_create_return_same_retirement() {
+        let server = fixture().await;
+        let binding = server.binding();
+        // Drop the original reply after headers: terminal state must already be durable.
+        let first = server.operation(&binding, "cancel").await;
+        assert_eq!(first.status(), reqwest::StatusCode::OK);
+        drop(first);
+        let replay = server.operation(&binding, "cancel").await;
+        assert_eq!(replay.status(), reqwest::StatusCode::OK);
+        let ack: UnallocatedAck = replay.json().await.unwrap();
+        ack.validate(&binding).unwrap();
+        let delayed = server.operation(&binding, "create").await;
+        assert_eq!(delayed.status(), reqwest::StatusCode::OK);
+        assert_eq!(delayed.json::<UnallocatedAck>().await.unwrap(), ack);
+        let journal = Journal::open(server.data.path()).await.unwrap();
+        assert_eq!(journal.retirement(&binding).unwrap(), Some(ack));
+        assert!(journal.load(&binding).unwrap().is_none());
+        assert!(!server.data.path().join("content-snapshots").exists());
+    }
+    #[tokio::test]
+    async fn cancellation_http_rejects_missing_proof_body_tamper_and_wrong_seller_without_tombstone(
+    ) {
+        let server = fixture().await;
+        let binding = server.binding();
+        let body = serde_json::to_vec(&Operation {
+            binding: binding.clone(),
+            action: "cancel".into(),
+        })
+        .unwrap();
+        assert!(!server.send(&body, None, None).await.status().is_success());
+        let mut changed = binding.clone();
+        changed.price_sats += 1;
+        let changed = serde_json::to_vec(&Operation {
+            binding: changed,
+            action: "cancel".into(),
+        })
+        .unwrap();
+        assert!(!server
+            .send(&changed, Some(&body), None)
+            .await
+            .status()
+            .is_success());
+        let wrong = crate::identity::did_key_from_pubkey_hex(&hex::encode([8; 32])).unwrap();
+        assert!(!server
+            .send(&body, Some(&body), Some(&wrong))
+            .await
+            .status()
+            .is_success());
+        let journal = Journal::open(server.data.path()).await.unwrap();
+        assert!(journal.retirement(&binding).unwrap().is_none());
+    }
+    #[tokio::test]
+    async fn authenticated_cancel_cannot_retire_dispatched_or_issued_address() {
+        let server = fixture().await;
+        let mut script = vec![0, 20];
+        script.extend([1; 20]);
+        let address = bitcoin::Address::from_script(
+            &bitcoin::ScriptBuf::from_bytes(script),
+            bitcoin::Network::Regtest,
+        )
+        .unwrap()
+        .to_string();
+        for allocation in [Allocation::Dispatched, Allocation::Ready { address }] {
+            let binding = server.binding();
+            let journal = Journal::open(server.data.path()).await.unwrap();
+            let mut record = journal
+                .prepare(
+                    binding.clone(),
+                    crate::content_lightning::RetainedFile {
+                        sha256: "a".repeat(64),
+                        size: 4,
+                        filename: "original.txt".into(),
+                        mime_type: "text/plain".into(),
+                    },
+                    crate::content_onchain::ChainNetwork::Regtest,
+                )
+                .unwrap();
+            record.allocation = allocation.clone();
+            journal.save(&record).unwrap();
+            drop(journal);
+            assert!(!server
+                .operation(&binding, "cancel")
+                .await
+                .status()
+                .is_success());
+            let journal = Journal::open(server.data.path()).await.unwrap();
+            assert!(journal.retirement(&binding).unwrap().is_none());
+            assert_eq!(
+                journal.load(&binding).unwrap().unwrap().allocation,
+                allocation
+            );
+        }
+    }
+    async fn seed_unallocated_offer(server: &HttpFixture) -> Binding {
+        let binding = server.binding();
+        crate::content_server::save_catalog(
+            server.data.path(),
+            &crate::content_server::ContentCatalog {
+                items: vec![crate::content_server::ContentItem {
+                    id: binding.content_id.clone(),
+                    filename: "original.txt".into(),
+                    mime_type: "text/plain".into(),
+                    size_bytes: 4,
+                    description: String::new(),
+                    added_at: String::new(),
+                    availability: crate::content_server::Availability::AllPeers,
+                    access: crate::content_server::AccessControl::Paid {
+                        price_sats: 546,
+                        accepted: vec!["onchain".into()],
+                    },
+                }],
+            },
+        )
+        .await
+        .unwrap();
+        let root = server.data.path().join("content/files");
+        std::fs::create_dir_all(&root).unwrap();
+        std::fs::write(root.join("original.txt"), b"test").unwrap();
+        let cancelled = std::sync::atomic::AtomicBool::new(false);
+        let snapshot = crate::content_snapshot::prepare(
+            server.data.path(),
+            &root,
+            &binding.content_id,
+            std::path::Path::new("original.txt"),
+            &crate::media_registration::Limits {
+                max_bytes: 1024,
+                cancelled: &cancelled,
+            },
+            1024 * 1024,
+            0,
+            |_| Ok(()),
+        )
+        .unwrap();
+        let journal = Journal::open(server.data.path()).await.unwrap();
+        journal
+            .prepare(
+                binding.clone(),
+                crate::content_lightning::RetainedFile {
+                    sha256: snapshot.sha256,
+                    size: 4,
+                    filename: "original.txt".into(),
+                    mime_type: "text/plain".into(),
+                },
+                crate::content_onchain::ChainNetwork::Regtest,
+            )
+            .unwrap();
+        binding
+    }
+
+    #[tokio::test]
+    async fn authenticated_offer_never_allocates_or_returns_a_receive_address() {
+        let server = fixture().await;
+        let binding = seed_unallocated_offer(&server).await;
+        let result = server.operation(&binding, "offer").await;
+        assert_eq!(result.status(), reqwest::StatusCode::OK);
+        let body: serde_json::Value = result.json().await.unwrap();
+        assert_eq!(body["allocation"]["state"], "prepared");
+        assert!(body["allocation"].get("address").is_none());
+        assert!(body.get("address").is_none());
+        let journal = Journal::open(server.data.path()).await.unwrap();
+        assert_eq!(
+            journal.load(&binding).unwrap().unwrap().allocation,
+            Allocation::Prepared
+        );
+    }
+
+    #[tokio::test]
+    async fn reviewed_offer_can_cancel_and_delayed_explicit_allocate_cannot_revive_it() {
+        let server = fixture().await;
+        let binding = seed_unallocated_offer(&server).await;
+        assert_eq!(
+            server.operation(&binding, "offer").await.status(),
+            reqwest::StatusCode::OK
+        );
+        let retired: UnallocatedAck = server
+            .operation(&binding, "cancel")
+            .await
+            .json()
+            .await
+            .unwrap();
+        retired.validate(&binding).unwrap();
+        // Represents a delayed Pay request from the old modal after cancellation.
+        let late = server.operation(&binding, "allocate").await;
+        assert_eq!(late.status(), reqwest::StatusCode::OK);
+        assert_eq!(late.json::<UnallocatedAck>().await.unwrap(), retired);
+        let journal = Journal::open(server.data.path()).await.unwrap();
+        assert_eq!(
+            journal.load(&binding).unwrap().unwrap().allocation,
+            Allocation::Prepared
+        );
+        assert_eq!(journal.retirement(&binding).unwrap(), Some(retired));
+    }
+
+    #[tokio::test]
+    async fn changing_authenticated_offer_body_to_allocate_cannot_dispatch_an_address() {
+        let server = fixture().await;
+        let binding = seed_unallocated_offer(&server).await;
+        let reviewed = serde_json::to_vec(&Operation {
+            binding: binding.clone(),
+            action: "offer".into(),
+        })
+        .unwrap();
+        let changed = serde_json::to_vec(&Operation {
+            binding: binding.clone(),
+            action: "allocate".into(),
+        })
+        .unwrap();
+        assert!(!server
+            .send(&changed, Some(&reviewed), None)
+            .await
+            .status()
+            .is_success());
+        let journal = Journal::open(server.data.path()).await.unwrap();
+        assert_eq!(
+            journal.load(&binding).unwrap().unwrap().allocation,
+            Allocation::Prepared
+        );
+        assert!(journal.retirement(&binding).unwrap().is_none());
+    }
+
+    #[tokio::test]
+    async fn explicit_allocation_reuses_original_address_after_lost_http_reply() {
+        let server = fixture().await;
+        let binding = seed_unallocated_offer(&server).await;
+        assert!(server
+            .operation(&binding, "offer")
+            .await
+            .status()
+            .is_success());
+        assert_eq!(
+            server
+                .wallet
+                .allocations
+                .load(std::sync::atomic::Ordering::SeqCst),
+            0
+        );
+        // Caller loses the response after seller durability; recovery returns the same record.
+        drop(server.operation(&binding, "allocate").await);
+        let recovered: crate::content_onchain_seller::Record = server
+            .operation(&binding, "allocate")
+            .await
+            .json()
+            .await
+            .unwrap();
+        assert!(recovered.quote().unwrap().is_some());
+        let repeated: crate::content_onchain_seller::Record = server
+            .operation(&binding, "allocate")
+            .await
+            .json()
+            .await
+            .unwrap();
+        assert_eq!(recovered, repeated);
+        assert_eq!(
+            server
+                .wallet
+                .allocations
+                .load(std::sync::atomic::Ordering::SeqCst),
+            1
+        );
+        assert!(!server
+            .operation(&binding, "cancel")
+            .await
+            .status()
+            .is_success());
+    }
+    #[tokio::test]
+    async fn lost_wallet_allocation_reply_never_allocates_a_second_address() {
+        let server = fixture().await;
+        let binding = seed_unallocated_offer(&server).await;
+        server
+            .wallet
+            .lose_reply
+            .store(true, std::sync::atomic::Ordering::SeqCst);
+        assert!(!server
+            .operation(&binding, "allocate")
+            .await
+            .status()
+            .is_success());
+        let recovered: crate::content_onchain_seller::Record = server
+            .operation(&binding, "allocate")
+            .await
+            .json()
+            .await
+            .unwrap();
+        assert_eq!(recovered.allocation, Allocation::Dispatched);
+        assert!(recovered.quote().unwrap().is_none());
+        assert_eq!(
+            server
+                .wallet
+                .allocations
+                .load(std::sync::atomic::Ordering::SeqCst),
+            1
+        );
+        assert!(!server
+            .operation(&binding, "cancel")
+            .await
+            .status()
+            .is_success());
+    }
+}

core/archipelago/src/api/handler/proxy.rs

@@ -138,6 +138,19 @@ impl ApiHandler {
         cors_origin: &str,
     ) -> Result<Response<hyper::Body>> {
         let suffix = path.strip_prefix("/proxy/lnd").unwrap_or("/");
+        if suffix == "/archy-status" {
+            return Ok(Response::builder()
+                .status(StatusCode::OK)
+                .header("Content-Type", "application/json")
+                .header("Cache-Control", "no-store")
+                .header("Access-Control-Allow-Origin", cors_origin)
+                .header("Access-Control-Allow-Credentials", "true")
+                .header("Vary", "Origin")
+                .body(hyper::Body::from(
+                    rpc.handle_lnd_readiness().await.to_string(),
+                ))?);
+        }
+
         let url = format!("{LND_REST_BASE_URL}{suffix}");
         // LND REST serves a self-signed cert and requires the admin macaroon.
         // A bare reqwest::get() uses the default client, which rejects the
@@ -225,54 +238,13 @@ impl ApiHandler {
             return bad("invalid onion or content id");
         }
 
-        // Already purchased? Serve the local cache — no network, no
-        // re-payment. The seller's node charges every fetch by design; the
-        // buyer-side store (content_owned) exists precisely so an owned item
-        // never has to be bought twice, and the content surface's cards were
-        // hitting the seller's 402 and rendering as permanent placeholders.
-        // Range is honoured by slicing, so seek/playback works from cache.
-        if crate::content_owned::is_owned(&self.config.data_dir, onion, content_id).await {
-            if let Some((mime_type, bytes)) =
-                crate::content_owned::read_owned(&self.config.data_dir, onion, content_id).await
-            {
-                let total = bytes.len();
-                let range = headers
-                    .get("range")
-                    .and_then(|v| v.to_str().ok())
-                    .and_then(crate::content_server::parse_range_header);
-                if let Some(r) = range {
-                    let start = (r.start as usize).min(total);
-                    let end = r
-                        .end
-                        .map(|e| e as usize)
-                        .unwrap_or(total.saturating_sub(1))
-                        .min(total.saturating_sub(1));
-                    if start <= end && total > 0 {
-                        let slice = &bytes[start..=end];
-                        return Ok(Response::builder()
-                            .status(StatusCode::PARTIAL_CONTENT)
-                            .header("Content-Type", mime_type)
-                            .header("Content-Length", slice.len().to_string())
-                            .header(
-                                "Content-Range",
-                                format!("bytes {}-{}/{}", start, end, total),
-                            )
-                            .header("Accept-Ranges", "bytes")
-                            .body(hyper::Body::from(slice.to_vec()))
-                            .unwrap_or_else(|_| Response::new(hyper::Body::empty())));
-                    }
-                }
-                return Ok(Response::builder()
-                    .status(StatusCode::OK)
-                    .header("Content-Type", mime_type)
-                    .header("Content-Length", total.to_string())
-                    .header("Accept-Ranges", "bytes")
-                    .body(hyper::Body::from(bytes))
-                    .unwrap_or_else(|_| Response::new(hyper::Body::empty())));
-            }
-            // Indexed as owned but bytes missing — fall through to the peer
-            // rather than erroring: the seller can still serve it (for the
-            // price already paid, the operator can re-fetch and re-cache).
+        // Ownership is checked before opening a bounded file stream. Corrupt
+        // records or missing purchased bytes never trigger another purchase.
+        match crate::content_owned::open_owned(&self.config.data_dir, onion, content_id).await {
+            Ok(Some((mime, file))) => return crate::media_stream::file_response(file, &mime, headers).await,
+            Ok(None) => {},
+            Err(_) => return Ok(build_response(StatusCode::CONFLICT, "application/json",
+                hyper::Body::from(serde_json::json!({"error": "Purchased file unavailable locally. Recover the existing purchase without paying again."}).to_string()))),
         }
 
         let fips_npub = crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;
@@ -280,20 +252,31 @@ impl ApiHandler {
         // Generous overall timeout: this endpoint serves both seek/Range
         // playback (small, finishes fast) and full-file downloads of large
         // media (#38). 60s was too tight for a multi-hundred-MB transfer over
-        // Tor and aborted the download mid-stream.
+        // slow links and aborted the download mid-stream.
         let mut req = crate::fips::dial::PeerRequest::new(fips_npub.as_deref(), onion, &peer_path)
             .service(crate::settings::transport::PeerService::PeerFiles)
+            .require_fips()
+            .record_transport(&self.config.data_dir)
             .timeout(std::time::Duration::from_secs(900));
         if let Some(r) = headers.get("range").and_then(|v| v.to_str().ok()) {
             req = req.header("Range", r.to_string());
         }
+        let req = req.authenticate_content(&self.config.data_dir).await?;
         match req.send_get().await {
-            Ok((resp, _transport)) => {
+            Ok((resp, transport)) => {
+                if resp.status().is_redirection() {
+                    return Ok(build_response(
+                        StatusCode::BAD_GATEWAY,
+                        "application/json",
+                        hyper::Body::from("{\"error\":\"Peer media redirects are not allowed\"}"),
+                    ));
+                }
                 let status = resp.status().as_u16();
                 let rh = resp.headers().clone();
                 let mut builder = Response::builder()
                     .status(status)
-                    .header("Accept-Ranges", "bytes");
+                    .header("Accept-Ranges", "bytes")
+                    .header("X-Archipelago-Transport", transport.to_string());
                 for h in ["content-type", "content-range", "content-length"] {
                     if let Some(v) = rh.get(h).and_then(|v| v.to_str().ok()) {
                         builder = builder.header(h, v);

core/archipelago/src/api/handler/purchase.rs

@@ -0,0 +1,206 @@
+//! Add as api/handler/purchase.rs; dispatch only exact supported POST routes.
+use super::{build_response, ApiHandler};
+use crate::{
+    content_purchase::Journal, content_purchase_protocol as protocol, identity::NodeIdentity,
+};
+use anyhow::{Context, Result};
+use hyper::{body::HttpBody, Body, Method, Request, Response, StatusCode};
+use serde::Deserialize;
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct OfferRequest {
+    id: String,
+    content_id: String,
+}
+impl ApiHandler {
+    pub(super) async fn handle_purchase_request(
+        &self,
+        mut request: Request<Body>,
+    ) -> Result<Response<Body>> {
+        let path = request.uri().path().to_owned();
+        anyhow::ensure!(
+            request.method() == Method::POST
+                && matches!(
+                    path.as_str(),
+                    protocol::PREPARE_OFFER_ROUTE
+                        | protocol::OFFER_ROUTE
+                        | protocol::ACCEPT_ROUTE
+                        | protocol::SETTLE_ROUTE
+                        | protocol::STATUS_ROUTE
+                        | protocol::CANCEL_ROUTE
+                ),
+            "Unsupported purchase route"
+        );
+        let audience = crate::identity::did_key_from_pubkey_hex(&self.self_pubkey_hex)?;
+        let bytes = tokio::time::timeout(std::time::Duration::from_secs(15), async {
+            let mut bytes = Vec::new();
+            while let Some(chunk) = request.body_mut().data().await {
+                let chunk = chunk?;
+                anyhow::ensure!(
+                    bytes
+                        .len()
+                        .checked_add(chunk.len())
+                        .is_some_and(|n| n <= 1024 * 1024),
+                    "Purchase body too large"
+                );
+                bytes.extend_from_slice(&chunk);
+            }
+            Ok::<_, anyhow::Error>(bytes)
+        })
+        .await
+        .context("Purchase body timed out")??;
+        let buyer = crate::content_auth::authenticate_request(
+            request.headers(),
+            &audience,
+            &Method::POST,
+            &path,
+            &bytes,
+            chrono::Utc::now().timestamp(),
+        )?;
+        let data_dir = &self.config.data_dir;
+        let result = match path.as_str() {
+            protocol::PREPARE_OFFER_ROUTE => {
+                #[derive(Deserialize)]
+                #[serde(deny_unknown_fields)]
+                struct Prepare {
+                    content_id: String,
+                    #[serde(default)]
+                    retry: bool,
+                    expected: Option<crate::content_purchase_caller::ExpectedRental>,
+                }
+                let input: Prepare = serde_json::from_slice(&bytes)?;
+                let identity = std::sync::Arc::new(
+                    NodeIdentity::load_existing(&data_dir.join("identity")).await?,
+                );
+                anyhow::ensure!(identity.did_key()? == audience, "Node identity changed");
+                let root = data_dir.clone();
+                serde_json::to_value(
+                    tokio::task::spawn_blocking(move || {
+                        if let Some(expected) = &input.expected {
+                            let (receipt, _) = crate::registered_media::registered_metadata(
+                                &root,
+                                &identity,
+                                &input.content_id,
+                            )?;
+                            expected.verify_metadata(&identity.did_key()?, &receipt)?;
+                        }
+                        crate::registered_media::prepare_registered(
+                            root,
+                            identity,
+                            &input.content_id,
+                            input.retry,
+                        )
+                    })
+                    .await??,
+                )?
+            }
+            protocol::OFFER_ROUTE => {
+                let body: OfferRequest = serde_json::from_slice(&bytes)?;
+                anyhow::ensure!(
+                    uuid::Uuid::parse_str(&body.id)?.to_string() == body.id,
+                    "Invalid operation identifier"
+                );
+                let saved = {
+                    Journal::open(data_dir)
+                        .await?
+                        .protocol_offer(&body.id)
+                        .await?
+                };
+                let offer = if let Some(saved) = saved {
+                    anyhow::ensure!(
+                        saved.buyer_did == buyer && saved.content_id == body.content_id,
+                        "Original offer binding changed"
+                    );
+                    saved
+                } else {
+                    // Registration pins and immutable snapshot are node-owned;
+                    // no content hash/price/path is accepted from the request.
+                    if !body.content_id.starts_with("registered_") {
+                        let wallet = crate::wallet::ecash::load_wallet(data_dir).await?;
+                        let offer = crate::content_cloud_offer::offer(
+                            data_dir,
+                            &body.id,
+                            &body.content_id,
+                            &buyer,
+                            &audience,
+                            crate::wallet::ecash::load_network(data_dir).await?,
+                            wallet.mint_url.trim_end_matches('/'),
+                            crate::content_cloud_offer::SnapshotPolicy {
+                                max_file_bytes: 64 * 1024 * 1024 * 1024,
+                                max_total_bytes: 64 * 1024 * 1024 * 1024,
+                                minimum_free_bytes: 512 * 1024 * 1024,
+                            },
+                        )
+                        .await?;
+                        return Ok(build_response(
+                            StatusCode::OK,
+                            "application/json",
+                            Body::from(serde_json::to_vec(&offer)?),
+                        ));
+                    }
+                    let identity = NodeIdentity::load_existing(&data_dir.join("identity")).await?;
+                    anyhow::ensure!(identity.did_key()? == audience, "Node identity changed");
+                    let selected = body.content_id.clone();
+                    let root = data_dir.clone();
+                    let (receipt, terms) = tokio::task::spawn_blocking(move || {
+                        crate::registered_media::registered_terms(&root, &identity, &selected)
+                    })
+                    .await??;
+                    anyhow::ensure!(
+                        receipt
+                            .payment_methods
+                            .iter()
+                            .any(|method| method == "cashu"),
+                        "Content does not accept Cashu"
+                    );
+                    let now = chrono::Utc::now().timestamp();
+                    let deadline = now.checked_add(120).context("Offer clock overflow")?;
+                    let wallet = crate::wallet::ecash::load_wallet(data_dir).await?;
+                    let offer = protocol::Offer {
+                        id: body.id,
+                        buyer_did: buyer.clone(),
+                        seller_did: audience.clone(),
+                        filename: receipt.content_id.clone(),
+                        mime_type: "application/octet-stream".into(),
+                        content_id: receipt.content_id,
+                        content_sha256: receipt.sha256,
+                        content_size: receipt.size_bytes.parse()?,
+                        viewing_seconds: Some(receipt.viewing_seconds),
+                        terms_sha256: terms,
+                        network: crate::wallet::ecash::load_network(data_dir).await?,
+                        mint_url: wallet.mint_url.trim_end_matches('/').to_owned(),
+                        seller_net_sats: receipt.price_sats,
+                        offered_at: now,
+                        expires_at: deadline,
+                    };
+                    protocol::save_offer(data_dir, &offer, &buyer, now).await?
+                };
+                protocol::ensure_seller_mint_policy(data_dir, offer.network, &offer.mint_url)
+                    .await?;
+                serde_json::to_value(offer)?
+            }
+            protocol::ACCEPT_ROUTE => serde_json::to_value(
+                protocol::accept(data_dir, &serde_json::from_slice(&bytes)?, &buyer, || {
+                    chrono::Utc::now().timestamp()
+                })
+                .await?,
+            )?,
+            protocol::SETTLE_ROUTE => serde_json::to_value(
+                protocol::settle(data_dir, &serde_json::from_slice(&bytes)?, &buyer).await?,
+            )?,
+            protocol::CANCEL_ROUTE => serde_json::to_value(
+                protocol::cancel(data_dir, &serde_json::from_slice(&bytes)?, &buyer).await?,
+            )?,
+            protocol::STATUS_ROUTE => serde_json::to_value(
+                protocol::status(data_dir, &serde_json::from_slice(&bytes)?, &buyer).await?,
+            )?,
+            _ => unreachable!(),
+        };
+        Ok(build_response(
+            StatusCode::OK,
+            "application/json",
+            Body::from(serde_json::to_vec(&result)?),
+        ))
+    }
+}

core/archipelago/src/api/handler/registered_media.rs

@@ -0,0 +1,437 @@
+//! Authenticated immutable rental streaming, separate from legacy mutable shares.
+use super::{build_response, ApiHandler};
+use crate::{content_server::ByteRange, identity::NodeIdentity, registered_media::OpenedMedia};
+use anyhow::{Context, Result};
+use hyper::{Body, HeaderMap, Response, StatusCode};
+use std::sync::Arc;
+
+fn route(path: &str) -> Result<(&str, &str)> {
+    let (content, purchase) = path
+        .strip_prefix("/content/")
+        .and_then(|value| value.split_once("/rental/"))
+        .context("Invalid rental route")?;
+    anyhow::ensure!(
+        content.starts_with("registered_") && !content.contains('/') && !purchase.contains('/'),
+        "Invalid rental identifiers"
+    );
+    let id = uuid::Uuid::parse_str(purchase)?;
+    anyhow::ensure!(
+        id.to_string() == purchase && id.get_version_num() == 4,
+        "Invalid purchase identifier"
+    );
+    Ok((content, purchase))
+}
+fn bounds(range: Option<ByteRange>, total: u64) -> Result<Option<(u64, u64)>> {
+    let Some(range) = range else {
+        anyhow::ensure!(total > 0, "Registered media is empty");
+        return Ok(None);
+    };
+    let last = total.checked_sub(1).context("Registered media is empty")?;
+    let (start, end) = match range {
+        ByteRange::From { start, end } => (start, end.unwrap_or(last).min(last)),
+        ByteRange::Suffix(count) => {
+            anyhow::ensure!(count > 0, "Invalid suffix range");
+            (total.saturating_sub(count), last)
+        }
+    };
+    anyhow::ensure!(start <= end && start < total, "Invalid rental byte range");
+    Ok(Some((start, end)))
+}
+fn clock() -> u64 {
+    u64::try_from(chrono::Utc::now().timestamp()).unwrap_or(0)
+}
+fn denied(message: &'static str) -> Response<Body> {
+    build_response(StatusCode::FORBIDDEN, "text/plain", Body::from(message))
+}
+
+impl ApiHandler {
+    pub(super) async fn handle_rental_control(
+        &self,
+        mut request: hyper::Request<Body>,
+    ) -> Result<Response<Body>> {
+        use hyper::body::HttpBody;
+        #[derive(serde::Deserialize)]
+        #[serde(deny_unknown_fields)]
+        struct Control {
+            capability: String,
+            ready_id: Option<String>,
+            #[serde(default)]
+            retry: bool,
+        }
+        let path = request.uri().path().to_owned();
+        let (base, action) = path.rsplit_once('/').context("Invalid rental action")?;
+        anyhow::ensure!(
+            matches!(action, "prepare" | "start") && request.method() == hyper::Method::POST,
+            "Invalid rental action"
+        );
+        let (content, purchase) = route(base)?;
+        let bytes = tokio::time::timeout(std::time::Duration::from_secs(15), async {
+            let mut bytes = Vec::new();
+            while let Some(chunk) = request.body_mut().data().await {
+                let chunk = chunk?;
+                anyhow::ensure!(
+                    bytes
+                        .len()
+                        .checked_add(chunk.len())
+                        .is_some_and(|n| n <= 16 * 1024),
+                    "Rental request too large"
+                );
+                bytes.extend_from_slice(&chunk);
+            }
+            Ok::<_, anyhow::Error>(bytes)
+        })
+        .await
+        .context("Rental request timed out")??;
+        let audience = crate::identity::did_key_from_pubkey_hex(&self.self_pubkey_hex)?;
+        let buyer = crate::content_auth::authenticate_request(
+            request.headers(),
+            &audience,
+            &hyper::Method::POST,
+            &path,
+            &bytes,
+            chrono::Utc::now().timestamp(),
+        )?;
+        let input: Control = serde_json::from_slice(&bytes)?;
+        let identity =
+            Arc::new(NodeIdentity::load_existing(&self.config.data_dir.join("identity")).await?);
+        anyhow::ensure!(identity.did_key()? == audience, "Node identity changed");
+        let result = if action == "prepare" {
+            anyhow::ensure!(input.ready_id.is_none(), "Prepare does not start a rental");
+            let prior = crate::registered_media::paid_window(
+                &self.config.data_dir,
+                &identity,
+                content,
+                purchase,
+                &buyer,
+                &input.capability,
+            )
+            .await?;
+            let metadata = crate::registered_media::registered_metadata(
+                &self.config.data_dir,
+                &identity,
+                content,
+            )?;
+            anyhow::ensure!(
+                prior
+                    .as_ref()
+                    .is_none_or(|window| clock() >= window.started_at),
+                "Rental clock moved backwards"
+            );
+            if let Some(window) = prior.as_ref().filter(|window| clock() >= window.expires_at) {
+                serde_json::json!({"state":"expired", "viewing_seconds":metadata.0.viewing_seconds,"started_at":window.started_at,"expires_at":window.expires_at})
+            } else {
+                let state = crate::registered_media::prepare_paid(
+                    self.config.data_dir.clone(),
+                    identity,
+                    content.into(),
+                    purchase.into(),
+                    buyer,
+                    input.capability,
+                    input.retry,
+                )
+                .await?;
+                let mut result = serde_json::to_value(state)?;
+                result["viewing_seconds"] = serde_json::json!(metadata.0.viewing_seconds);
+                result["started_at"] =
+                    serde_json::json!(prior.as_ref().map(|window| window.started_at));
+                result["expires_at"] =
+                    serde_json::json!(prior.as_ref().map(|window| window.expires_at));
+                result
+            }
+        } else {
+            anyhow::ensure!(!input.retry, "Start cannot retry verification");
+            let ready_id = input
+                .ready_id
+                .context("Media must be ready before explicit Start")?;
+            let window = crate::registered_media::start_paid(
+                self.config.data_dir.clone(),
+                identity,
+                content.into(),
+                purchase.into(),
+                buyer,
+                input.capability,
+                ready_id,
+            )
+            .await?;
+            anyhow::ensure!(clock() >= window.started_at, "Rental clock moved backwards");
+            serde_json::json!({"state": if clock() >= window.expires_at {"expired"} else {"started"},
+                "started_at":window.started_at,"expires_at":window.expires_at})
+        };
+        Ok(build_response(
+            StatusCode::OK,
+            "application/json",
+            Body::from(serde_json::to_vec(&result)?),
+        ))
+    }
+
+    pub(super) async fn handle_registered_rental(
+        &self,
+        path: &str,
+        headers: &HeaderMap,
+    ) -> Result<Response<Body>> {
+        let (content, purchase) = match route(path) {
+            Ok(ids) => ids,
+            Err(_) => {
+                return Ok(build_response(
+                    StatusCode::BAD_REQUEST,
+                    "text/plain",
+                    Body::from("Invalid rental route"),
+                ))
+            }
+        };
+        let audience = crate::identity::did_key_from_pubkey_hex(&self.self_pubkey_hex)?;
+        let buyer = match crate::content_auth::incoming(
+            headers,
+            &audience,
+            path,
+            chrono::Utc::now().timestamp(),
+        ) {
+            Ok(Some(buyer)) => buyer,
+            _ => return Ok(denied("Authenticated node proof is required")),
+        };
+        let capability = match headers
+            .get("x-content-capability")
+            .and_then(|v| v.to_str().ok())
+        {
+            Some(value) if value.len() == 64 => value.to_owned(),
+            _ => return Ok(denied("Original purchase capability is required")),
+        };
+        let requested_range = match headers.get("range") {
+            None => None,
+            Some(value) => match value
+                .to_str()
+                .ok()
+                .and_then(crate::content_server::parse_range_header)
+            {
+                Some(range) => Some(range),
+                None => {
+                    return Ok(build_response(
+                        StatusCode::RANGE_NOT_SATISFIABLE,
+                        "text/plain",
+                        Body::from("Invalid byte range"),
+                    ))
+                }
+            },
+        };
+        let identity =
+            Arc::new(NodeIdentity::load_existing(&self.config.data_dir.join("identity")).await?);
+        anyhow::ensure!(identity.did_key()? == audience, "Node identity changed");
+        let data = self.config.data_dir.clone();
+        let selected = content.to_owned();
+        let key = identity.clone();
+        let metadata = tokio::task::spawn_blocking(move || {
+            crate::registered_media::registered_metadata(&data, &key, &selected)
+        })
+        .await?;
+        let (receipt, _) = match metadata {
+            Ok(value) => value,
+            Err(_) => {
+                return Ok(build_response(
+                    StatusCode::NOT_FOUND,
+                    "text/plain",
+                    Body::from("Registered content is unavailable"),
+                ))
+            }
+        };
+        let total = receipt.size_bytes.parse::<u64>()?;
+        let range = match bounds(requested_range, total) {
+            Ok(value) => value,
+            Err(_) => {
+                return Ok(Response::builder()
+                    .status(StatusCode::RANGE_NOT_SATISFIABLE)
+                    .header("Content-Range", format!("bytes */{total}"))
+                    .body(Body::from("Invalid byte range"))?)
+            }
+        };
+        // All malformed/out-of-bounds requests are rejected before first-open
+        // rental creation. No payment or new receipt is attempted by this route.
+        let opened = match crate::registered_media::open_paid(
+            self.config.data_dir.clone(),
+            identity,
+            content.into(),
+            purchase.into(),
+            buyer,
+            capability,
+        )
+        .await
+        {
+            Ok(opened) => opened,
+            Err(_) => {
+                return Ok(denied(
+                    "This purchase is not settled, does not match, or its rental has expired",
+                ))
+            }
+        };
+        rental_response(opened, range, Arc::new(clock)).await
+    }
+}
+async fn rental_response(
+    opened: OpenedMedia,
+    range: Option<(u64, u64)>,
+    now: Arc<dyn Fn() -> u64 + Send + Sync>,
+) -> Result<Response<Body>> {
+    anyhow::ensure!(
+        opened.still_authorized(now()),
+        "Rental expired before streaming"
+    );
+    let total = opened.size_bytes;
+    let started = opened.started_at;
+    let expires = opened.expires_at;
+    let (start, length) = range.map_or((0, total), |(start, end)| (start, end - start + 1));
+    let chunks = futures_util::stream::try_unfold(
+        (opened.file, opened.verification, start, length, now),
+        move |(mut file, verification, position, left, now)| async move {
+            if left == 0 {
+                return Ok::<_, std::io::Error>(None);
+            }
+            let instant = now();
+            if instant < started || instant >= expires {
+                return Err(std::io::Error::new(
+                    std::io::ErrorKind::PermissionDenied,
+                    "Rental window ended",
+                ));
+            }
+            let read = tokio::task::spawn_blocking(move || {
+                let bytes = verification
+                    .index
+                    .read_slice(&mut file, position, left.min(64 * 1024) as usize)
+                    .map_err(std::io::Error::other)?;
+                Ok::<_, std::io::Error>((file, verification, bytes))
+            });
+            let (file, verification, bytes) =
+                tokio::time::timeout(std::time::Duration::from_secs(expires - instant), read)
+                    .await
+                    .map_err(|_| {
+                        std::io::Error::new(std::io::ErrorKind::TimedOut, "Rental window ended")
+                    })?
+                    .map_err(std::io::Error::other)??;
+            let instant = now();
+            if instant < started || instant >= expires {
+                return Err(std::io::Error::new(
+                    std::io::ErrorKind::PermissionDenied,
+                    "Rental window ended",
+                ));
+            }
+            let count = bytes.len() as u64;
+            Ok(Some((
+                bytes,
+                (file, verification, position + count, left - count, now),
+            )))
+        },
+    );
+    let mut response = Response::builder()
+        .status(if range.is_some() {
+            StatusCode::PARTIAL_CONTENT
+        } else {
+            StatusCode::OK
+        })
+        .header("Content-Type", opened.mime_type)
+        .header("Content-Length", length)
+        .header("Accept-Ranges", "bytes")
+        .header("X-Content-Type-Options", "nosniff")
+        .header("Cache-Control", "private, no-store")
+        .header("X-Rental-Expires-At", expires);
+    if let Some((start, end)) = range {
+        response = response.header("Content-Range", format!("bytes {start}-{end}/{total}"));
+    }
+    Ok(response.body(Body::wrap_stream(chunks))?)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use hyper::body::HttpBody;
+    use std::sync::atomic::{AtomicU64, Ordering};
+    #[test]
+    fn invalid_routes_and_ranges_cannot_reach_rental_creation() {
+        let id = uuid::Uuid::new_v4();
+        assert!(route(&format!("/content/registered_{id}/rental/{id}")).is_ok());
+        for path in [
+            format!("/content/registered_{id}/rental/{id}/extra"),
+            format!("/content/../rental/{id}"),
+            format!("/content/registered_{id}/rental/not-a-purchase"),
+        ] {
+            assert!(route(&path).is_err());
+        }
+        assert!(bounds(
+            Some(ByteRange::From {
+                start: 20,
+                end: None
+            }),
+            20
+        )
+        .is_err());
+        assert!(bounds(
+            Some(ByteRange::From {
+                start: 9,
+                end: Some(8)
+            }),
+            20
+        )
+        .is_err());
+        assert_eq!(
+            bounds(Some(ByteRange::Suffix(5)), 20).unwrap(),
+            Some((15, 19))
+        );
+    }
+    fn opened(size: u64) -> OpenedMedia {
+        use sha2::{Digest, Sha256};
+        let mut file = tempfile::tempfile().unwrap();
+        file.set_len(size).unwrap();
+        let binding = crate::rental_chunk_index::Binding {
+            content_id: format!("registered_{}", uuid::Uuid::new_v4()),
+            receipt_sha256: "ab".repeat(32),
+            full_sha256: hex::encode(Sha256::digest(vec![0; size as usize])),
+            size,
+        };
+        let index = crate::rental_chunk_index::Index::scan(&mut file, binding, |_| Ok(())).unwrap();
+        OpenedMedia {
+            file,
+            verification: crate::rental_readiness::Ready::fixture(index),
+            size_bytes: size,
+            mime_type: "video/mp4".into(),
+            started_at: 1000,
+            expires_at: 1060,
+        }
+    }
+    #[tokio::test]
+    async fn bounded_stream_stops_at_persisted_deadline_without_restarting_window() {
+        let clock = Arc::new(AtomicU64::new(1000));
+        let read_clock = clock.clone();
+        let mut response = rental_response(
+            opened(200_000),
+            None,
+            Arc::new(move || read_clock.load(Ordering::SeqCst)),
+        )
+        .await
+        .unwrap();
+        assert_eq!(response.headers()["x-rental-expires-at"], "1060");
+        assert_eq!(
+            response.body_mut().data().await.unwrap().unwrap().len(),
+            64 * 1024
+        );
+        clock.store(1060, Ordering::SeqCst);
+        assert!(response.body_mut().data().await.unwrap().is_err());
+    }
+    #[tokio::test]
+    async fn suffix_response_has_exact_length_and_expired_or_rollback_stream_denies() {
+        let mut response = rental_response(opened(20), Some((15, 19)), Arc::new(|| 1000))
+            .await
+            .unwrap();
+        assert_eq!(response.status(), StatusCode::PARTIAL_CONTENT);
+        assert_eq!(response.headers()["content-range"], "bytes 15-19/20");
+        assert_eq!(
+            hyper::body::to_bytes(response.body_mut())
+                .await
+                .unwrap()
+                .len(),
+            5
+        );
+        assert!(rental_response(opened(20), None, Arc::new(|| 1060))
+            .await
+            .is_err());
+        assert!(rental_response(opened(20), None, Arc::new(|| 999))
+            .await
+            .is_err());
+    }
+}

core/archipelago/src/api/handler/rental_playback.rs

@@ -0,0 +1,548 @@
+//! Local browser playback. Only opaque local handles cross the browser boundary.
+use super::{build_response, ApiHandler};
+use crate::{content_purchase::Journal, content_server::ByteRange, identity::NodeIdentity};
+use anyhow::{Context, Result};
+use hyper::{Body, HeaderMap, Method, Response, StatusCode};
+use std::{
+    io,
+    sync::Arc,
+    time::{Duration, Instant},
+};
+
+fn requested_bounds(headers: &HeaderMap, total: u64) -> Result<Option<(u64, u64)>> {
+    anyhow::ensure!(total > 0, "Empty purchased media");
+    anyhow::ensure!(
+        headers.get_all("range").iter().count() <= 1,
+        "Ambiguous playback ranges"
+    );
+    let Some(header) = headers.get("range") else {
+        return Ok(None);
+    };
+    let range = crate::content_server::parse_range_header(header.to_str()?)
+        .context("Invalid playback byte range")?;
+    let last = total - 1;
+    let (start, end) = match range {
+        ByteRange::From { start, end } => (start, end.unwrap_or(last).min(last)),
+        ByteRange::Suffix(count) => {
+            anyhow::ensure!(count > 0, "Invalid byte range");
+            (total.saturating_sub(count), last)
+        }
+    };
+    anyhow::ensure!(start <= end && start < total, "Invalid playback byte range");
+    Ok(Some((start, end)))
+}
+fn validate_upstream(
+    status: u16,
+    headers: &HeaderMap,
+    total: u64,
+    bounds: Option<(u64, u64)>,
+    now: u64,
+) -> Result<(u16, u64, String, u64)> {
+    let expected_status = if bounds.is_some() { 206 } else { 200 };
+    anyhow::ensure!(
+        status == expected_status,
+        "Seller returned another range status"
+    );
+    let length = bounds.map_or(total, |(start, end)| end - start + 1);
+    anyhow::ensure!(
+        headers
+            .get("content-length")
+            .and_then(|v| v.to_str().ok())
+            .and_then(|v| v.parse::<u64>().ok())
+            == Some(length),
+        "Seller changed purchased byte length"
+    );
+    if let Some((start, end)) = bounds {
+        let expected = format!("bytes {start}-{end}/{total}");
+        anyhow::ensure!(
+            headers.get("content-range").and_then(|v| v.to_str().ok()) == Some(expected.as_str()),
+            "Seller changed purchased byte range"
+        );
+    }
+    let mime = headers
+        .get("content-type")
+        .context("Missing media type")?
+        .to_str()?
+        .to_owned();
+    anyhow::ensure!(
+        mime.starts_with("video/") || mime.starts_with("audio/"),
+        "Unsupported rental media type"
+    );
+    let expires = headers
+        .get("x-rental-expires-at")
+        .context("Missing rental expiry")?
+        .to_str()?
+        .parse::<u64>()?;
+    anyhow::ensure!(expires > now, "Rental viewing window ended");
+    Ok((expected_status, length, mime, expires))
+}
+
+fn installed_playback_origin(
+    origin: &str,
+    expected: &str,
+    host: &str,
+    gated_tls_port: bool,
+) -> bool {
+    let (Ok(actual), Ok(expected), Ok(request)) = (
+        reqwest::Url::parse(origin),
+        reqwest::Url::parse(expected),
+        reqwest::Url::parse(&format!("http://{host}")),
+    ) else {
+        return false;
+    };
+    if !matches!(actual.scheme(), "http" | "https")
+        || actual.origin().ascii_serialization() != origin
+        || request.path() != "/"
+        || !request.username().is_empty()
+        || request.password().is_some()
+        || request.query().is_some()
+        || request.fragment().is_some()
+    {
+        return false;
+    }
+    if actual.origin() == expected.origin() {
+        return true;
+    }
+    let same_port = actual.port_or_known_default() == expected.port_or_known_default();
+    let scheme = actual.scheme() == expected.scheme()
+        || (gated_tls_port && actual.scheme() == "https" && expected.scheme() == "http");
+    let expected_loopback = matches!(
+        expected.host_str(),
+        Some("localhost" | "127.0.0.1" | "[::1]")
+    );
+    same_port
+        && scheme
+        && actual.host_str() == request.host_str()
+        && (expected_loopback || actual.host_str() == expected.host_str())
+}
+
+fn unix_now() -> Result<u64> {
+    Ok(std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)?
+        .as_secs())
+}
+fn stream_error(message: &'static str) -> io::Error {
+    io::Error::new(io::ErrorKind::PermissionDenied, message)
+}
+
+impl ApiHandler {
+    pub(super) async fn handle_local_rental_request(
+        &self,
+        method: &Method,
+        path: &str,
+        headers: &HeaderMap,
+    ) -> Result<Response<Body>> {
+        // HEAD is deliberately not GET: a browser probe must never open a lease.
+        if method != Method::GET && method != Method::OPTIONS {
+            return Ok(Response::builder()
+                .status(StatusCode::METHOD_NOT_ALLOWED)
+                .header("Allow", "GET, OPTIONS")
+                .header("Cache-Control", "no-store")
+                .body(Body::empty())?);
+        }
+        let origin = headers.get("origin").map(|v| v.to_str()).transpose()?;
+        if let Some(origin) = origin {
+            let identity =
+                NodeIdentity::load_existing(&self.config.data_dir.join("identity")).await?;
+            let (state, _) = self.state_manager.get_snapshot().await;
+            let root = self.config.data_dir.clone();
+            let context = tokio::task::spawn_blocking(move || {
+                crate::container::registration_pin::installed_context(&root, &identity, &state)
+            })
+            .await??;
+            let host = headers
+                .get("host")
+                .and_then(|value| value.to_str().ok())
+                .unwrap_or("");
+            let port = reqwest::Url::parse(origin)
+                .ok()
+                .and_then(|url| url.port_or_known_default());
+            let ports = self.rpc_handler.app_gate.port_map().await;
+            let gated_tls_port = port
+                .and_then(|port| ports.gated(port))
+                .is_some_and(|gate| gate.app_id == context.app_id && gate.declared);
+            if !context
+                .app_origins
+                .iter()
+                .any(|allowed| installed_playback_origin(origin, allowed, host, gated_tls_port))
+            {
+                return Ok(build_response(
+                    StatusCode::FORBIDDEN,
+                    "text/plain",
+                    Body::from("Playback origin is not the installed app"),
+                ));
+            }
+        }
+        let mut response = if method == Method::OPTIONS {
+            Response::builder()
+                .status(StatusCode::NO_CONTENT)
+                .body(Body::empty())?
+        } else {
+            self.handle_local_rental(path, headers).await?
+        };
+        response
+            .headers_mut()
+            .insert("Cache-Control", "private, no-store".parse()?);
+        response.headers_mut().insert("Vary", "Origin".parse()?);
+        if let Some(origin) = origin {
+            response
+                .headers_mut()
+                .insert("Access-Control-Allow-Origin", origin.parse()?);
+            response
+                .headers_mut()
+                .insert("Access-Control-Allow-Credentials", "true".parse()?);
+            response
+                .headers_mut()
+                .insert("Access-Control-Allow-Methods", "GET, OPTIONS".parse()?);
+            response
+                .headers_mut()
+                .insert("Access-Control-Allow-Headers", "Range".parse()?);
+            response.headers_mut().insert(
+                "Access-Control-Expose-Headers",
+                "Content-Length, Content-Range, Accept-Ranges, X-Rental-Expires-At".parse()?,
+            );
+        }
+        Ok(response)
+    }
+
+    /// Dispatcher accepts GET only after normal session handling. HEAD and other
+    /// methods never reach upstream, so metadata probes cannot start a lease.
+    pub(super) async fn handle_local_rental(
+        &self,
+        path: &str,
+        headers: &HeaderMap,
+    ) -> Result<Response<Body>> {
+        let token = match crate::session::extract_session_cookie(headers) {
+            Some(token) if self.session_store.validate(&token).await => token,
+            _ => return Ok(Self::unauthorized()),
+        };
+        let handle = path
+            .strip_prefix("/api/rental-playback/")
+            .context("Invalid playback route")?;
+        let identity =
+            Arc::new(NodeIdentity::load_existing(&self.config.data_dir.join("identity")).await?);
+        let (state, _) = self.state_manager.get_snapshot().await;
+        let root = self.config.data_dir.clone();
+        let key = identity.clone();
+        let context = tokio::task::spawn_blocking(move || {
+            crate::container::registration_pin::installed_context(&root, &key, &state)
+        })
+        .await??;
+        let binding = self
+            .rpc_handler
+            .playback_handles()
+            .lookup(handle, &token, &context)?;
+        let capability = {
+            let journal = Journal::open(&self.config.data_dir).await?;
+            let record = journal
+                .buyer(&binding.contract.id)
+                .await?
+                .context("Original purchase is missing")?;
+            anyhow::ensure!(
+                record.contract == binding.contract,
+                "Original purchase changed"
+            );
+            record
+                .receipt()
+                .context("Original purchase is not settled")?
+                .capability
+                .clone()
+        };
+        let peer = crate::federation::load_unique_payment_peer(
+            &self.config.data_dir,
+            &binding.seller_onion,
+        )
+        .await?;
+        anyhow::ensure!(
+            peer.did == binding.contract.seller_did,
+            "Purchased seller identity changed"
+        );
+        let mesh = peer
+            .fips_npub
+            .context("Seller mesh binding is unavailable")?;
+        let total = binding.contract.content_size;
+        let bounds = match requested_bounds(headers, total) {
+            Ok(bounds) => bounds,
+            Err(_) => {
+                return Ok(Response::builder()
+                    .status(StatusCode::RANGE_NOT_SATISFIABLE)
+                    .header("Content-Range", format!("bytes */{total}"))
+                    .body(Body::empty())?)
+            }
+        };
+        let remote_path = format!(
+            "/content/{}/rental/{}",
+            binding.contract.content_id, binding.contract.id
+        );
+        let mut request =
+            crate::fips::dial::PeerRequest::new(Some(&mesh), &binding.seller_onion, &remote_path)
+                .require_fips()
+                .single_delivery()
+                .timeout(Duration::from_secs(24 * 60 * 60))
+                .header("X-Content-Capability", capability);
+        if let Some((start, end)) = bounds {
+            request = request.header("Range", format!("bytes={start}-{end}"));
+        }
+        let (response, transport) = tokio::time::timeout(
+            Duration::from_secs(20),
+            request.send_content_get(&self.config.data_dir),
+        )
+        .await
+        .context("Seller did not begin the original rental stream")??;
+        if !response.status().is_success() {
+            // Never forward arbitrary upstream bodies, redirects, cookies or private headers.
+            let status = if response.status().as_u16() == 403 {
+                StatusCode::FORBIDDEN
+            } else {
+                StatusCode::BAD_GATEWAY
+            };
+            return Ok(build_response(
+                status,
+                "text/plain",
+                Body::from(
+                    "Original rental is unavailable; recover this purchase without paying again",
+                ),
+            ));
+        }
+        let (expected_status, length, mime, expires) = validate_upstream(
+            response.status().as_u16(),
+            response.headers(),
+            total,
+            bounds,
+            unix_now()?,
+        )?;
+        self.rpc_handler
+            .playback_handles()
+            .note_expiry(handle, &binding, expires)?;
+        let sessions = self.session_store.clone();
+        let state_manager = self.state_manager.clone();
+        let data_dir = self.config.data_dir.clone();
+        let chunks = futures_util::stream::try_unfold(
+            (response, length, None::<Instant>),
+            move |(mut response, left, mut checked)| {
+                let sessions = sessions.clone();
+                let token = token.clone();
+                let state_manager = state_manager.clone();
+                let data_dir = data_dir.clone();
+                let identity = identity.clone();
+                let context = context.clone();
+                async move {
+                    if unix_now().map_err(|_| stream_error("Playback clock unavailable"))?
+                        >= expires
+                    {
+                        return Err(stream_error("Rental viewing window ended"));
+                    }
+                    if left == 0 {
+                        return Ok::<_, io::Error>(None);
+                    }
+                    let waiting_since = Instant::now();
+                    loop {
+                        if waiting_since.elapsed() >= Duration::from_secs(30) {
+                            return Err(io::Error::new(
+                                io::ErrorKind::TimedOut,
+                                "Rental stream stalled; reopen the original purchase",
+                            ));
+                        }
+                        if unix_now().map_err(|_| stream_error("Playback clock unavailable"))?
+                            >= expires
+                        {
+                            return Err(stream_error("Rental viewing window ended"));
+                        }
+                        if checked.is_none_or(|at| at.elapsed() >= Duration::from_secs(1)) {
+                            if !sessions.validate(&token).await {
+                                return Err(stream_error("Playback session ended"));
+                            }
+                            let (state, _) = state_manager.get_snapshot().await;
+                            let root = data_dir.clone();
+                            let key = identity.clone();
+                            let actual = tokio::task::spawn_blocking(move || {
+                                crate::container::registration_pin::installed_context(
+                                    &root, &key, &state,
+                                )
+                            })
+                            .await
+                            .map_err(|_| stream_error("Playback app context unavailable"))?
+                            .map_err(|_| stream_error("Playback app context unavailable"))?;
+                            if actual != context {
+                                return Err(stream_error("Playback app context changed"));
+                            }
+                            checked = Some(Instant::now());
+                        }
+                        // Keep checking revocation while the peer stalls; no local media cache.
+                        let chunk = tokio::select! {
+                            chunk=response.chunk() => chunk.map_err(|_|io::Error::new(io::ErrorKind::ConnectionAborted,"Rental stream interrupted; reopen the original purchase"))?,
+                            _=tokio::time::sleep(Duration::from_secs(1)) => continue,
+                        };
+                        let bytes = chunk.ok_or_else(|| {
+                            io::Error::new(
+                                io::ErrorKind::UnexpectedEof,
+                                "Purchased media ended early",
+                            )
+                        })?;
+                        if bytes.len() as u64 > left {
+                            return Err(io::Error::new(
+                                io::ErrorKind::InvalidData,
+                                "Purchased media exceeded its declared length",
+                            ));
+                        }
+                        let remaining = left - bytes.len() as u64;
+                        return Ok(Some((bytes, (response, remaining, checked))));
+                    }
+                }
+            },
+        );
+        let mut result = Response::builder()
+            .status(expected_status)
+            .header("Content-Type", mime)
+            .header("Content-Length", length)
+            .header("Accept-Ranges", "bytes")
+            .header("Cache-Control", "private, no-store")
+            .header("X-Content-Type-Options", "nosniff")
+            .header("X-Rental-Expires-At", expires)
+            .header("X-Archipelago-Transport", transport.to_string());
+        if let Some((start, end)) = bounds {
+            result = result.header("Content-Range", format!("bytes {start}-{end}/{total}"));
+        }
+        Ok(result.body(Body::wrap_stream(chunks))?)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn installed_origin_maps_only_current_host_and_verified_app_port() {
+        assert!(installed_playback_origin(
+            "http://192.168.1.5:7778",
+            "http://127.0.0.1:7778",
+            "192.168.1.5",
+            false
+        ));
+        assert!(installed_playback_origin(
+            "https://192.168.1.5:7778",
+            "http://127.0.0.1:7778",
+            "192.168.1.5",
+            true
+        ));
+        assert!(installed_playback_origin(
+            "https://[fd00::5]:7778",
+            "https://[::1]:7778",
+            "[fd00::5]:443",
+            false
+        ));
+        for (actual, host, tls) in [
+            ("https://192.168.1.5:7778", "192.168.1.5", false),
+            ("http://evil.test:7778", "192.168.1.5", true),
+            ("http://192.168.1.5:7779", "192.168.1.5", true),
+            ("http://192.168.1.5:7778", "evil.test", true),
+            ("http://192.168.1.5:7778/path", "192.168.1.5", true),
+            ("http://192.168.1.5:7778", "user@192.168.1.5", true),
+        ] {
+            assert!(
+                !installed_playback_origin(actual, "http://127.0.0.1:7778", host, tls),
+                "{actual} {host}"
+            );
+        }
+    }
+
+    #[test]
+    fn range_bounds_follow_purchased_size_and_reject_ambiguous_ranges() {
+        let check = |range: &str| {
+            let mut h = HeaderMap::new();
+            h.insert("range", range.parse().unwrap());
+            requested_bounds(&h, 100)
+        };
+        assert_eq!(check("bytes=20-39").unwrap(), Some((20, 39)));
+        assert_eq!(check("bytes=90-").unwrap(), Some((90, 99)));
+        assert_eq!(check("bytes=-10").unwrap(), Some((90, 99)));
+        assert_eq!(check("bytes=-200").unwrap(), Some((0, 99)));
+        assert_eq!(check("bytes=90-500").unwrap(), Some((90, 99)));
+        for range in [
+            "bytes=100-",
+            "bytes=20-10",
+            "bytes=-0",
+            "bytes=0-1,4-6",
+            "other=0-1",
+        ] {
+            assert!(check(range).is_err(), "{range}");
+        }
+        assert_eq!(requested_bounds(&HeaderMap::new(), 100).unwrap(), None);
+        assert!(requested_bounds(&HeaderMap::new(), 0).is_err());
+    }
+    #[test]
+    fn upstream_range_expiry_and_media_headers_are_bound_before_bytes_escape() {
+        let mut headers = HeaderMap::new();
+        for (name, value) in [
+            ("content-length", "20"),
+            ("content-range", "bytes 20-39/100"),
+            ("content-type", "video/mp4"),
+            ("x-rental-expires-at", "200"),
+        ] {
+            headers.insert(name, value.parse().unwrap());
+        }
+        assert_eq!(
+            validate_upstream(206, &headers, 100, Some((20, 39)), 100).unwrap(),
+            (206, 20, "video/mp4".into(), 200)
+        );
+        assert!(validate_upstream(200, &headers, 100, Some((20, 39)), 100).is_err());
+        assert!(validate_upstream(206, &headers, 100, Some((20, 39)), 200).is_err());
+        for (name, bad) in [
+            ("content-length", "21"),
+            ("content-range", "bytes 21-40/100"),
+            ("content-type", "text/html"),
+            ("x-rental-expires-at", "0"),
+        ] {
+            let mut changed = headers.clone();
+            changed.insert(name, bad.parse().unwrap());
+            assert!(
+                validate_upstream(206, &changed, 100, Some((20, 39)), 100).is_err(),
+                "{name}"
+            );
+        }
+        headers.remove("content-range");
+        headers.insert("content-length", "100".parse().unwrap());
+        assert!(validate_upstream(200, &headers, 100, None, 100).is_ok());
+    }
+
+    #[tokio::test]
+    async fn metadata_probes_and_unauthenticated_get_do_not_touch_purchase_or_identity() {
+        let root = tempfile::tempdir().unwrap();
+        let mut config = crate::config::Config::default();
+        config.data_dir = root.path().to_path_buf();
+        let handler = ApiHandler::new(
+            config,
+            Arc::new(crate::state::StateManager::new()),
+            Arc::new(crate::monitoring::MetricsStore::new()),
+            None,
+            None,
+        )
+        .await
+        .unwrap();
+        // ApiHandler initialization may establish its own node identity, but the
+        // denied route must not need installed apps, saved receipts or any peer.
+        for method in [Method::HEAD, Method::POST] {
+            let result = handler
+                .handle_request(
+                    hyper::Request::builder()
+                        .method(method)
+                        .uri("/api/rental-playback/invalid")
+                        .body(Body::empty())
+                        .unwrap(),
+                )
+                .await
+                .unwrap();
+            assert_eq!(result.status(), StatusCode::METHOD_NOT_ALLOWED);
+        }
+        let result = handler
+            .handle_request(
+                hyper::Request::builder()
+                    .uri("/api/rental-playback/invalid")
+                    .body(Body::empty())
+                    .unwrap(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(result.status(), StatusCode::UNAUTHORIZED);
+        assert!(!root.path().join("content-purchases").exists());
+    }
+}

core/archipelago/src/api/rpc/analytics.rs

@@ -5,10 +5,47 @@
 
 use super::RpcHandler;
 use anyhow::{Context, Result};
+use std::collections::HashSet;
 use tracing::{debug, info, warn};
 
 const ANALYTICS_FILE: &str = "analytics-config.json";
 
+/// Collector reports are unsigned claims, including historical on-disk reports.
+/// Provenance is assigned here, never accepted from their JSON payload.
+fn collector_report(
+    mut report: serde_json::Value,
+    expected_id: Option<&str>,
+) -> Result<serde_json::Value> {
+    let id = report
+        .get("node_id")
+        .and_then(|v| v.as_str())
+        .context("Missing collector identity")?;
+    anyhow::ensure!(
+        !id.is_empty()
+            && id.len() <= 64
+            && !id.contains('/')
+            && !id.contains('\\')
+            && !id.contains("..")
+            && !id.ends_with("-history")
+            && !id.chars().any(char::is_control),
+        "Invalid collector identity"
+    );
+    anyhow::ensure!(
+        expected_id.is_none_or(|expected| expected == id),
+        "Collector identity differs from record"
+    );
+    let object = report.as_object_mut().context("Invalid collector report")?;
+    object.insert("source".into(), serde_json::json!("collector"));
+    object.insert("trust_level".into(), serde_json::json!("unverified"));
+    object.insert("identity_authenticated".into(), serde_json::json!(false));
+    Ok(report)
+}
+
+async fn federation_ids(data_dir: &std::path::Path) -> Result<HashSet<String>> {
+    // A damaged authoritative store must not promote unsigned collector data.
+    crate::federation::load_node_identities(data_dir).await
+}
+
 impl RpcHandler {
     /// Check if analytics are enabled.
     pub(super) async fn handle_analytics_get_status(&self) -> Result<serde_json::Value> {
@@ -262,7 +299,7 @@ impl RpcHandler {
         &self,
         params: Option<serde_json::Value>,
     ) -> Result<serde_json::Value> {
-        let report = params.context("Missing telemetry report payload")?;
+        let report = collector_report(params.context("Missing telemetry report payload")?, None)?;
 
         // Validate required fields
         let node_id = report
@@ -285,6 +322,13 @@ impl RpcHandler {
             .and_then(|v| v.as_str())
             .context("Missing required field: reported_at")?;
 
+        anyhow::ensure!(
+            !federation_ids(&self.config.data_dir)
+                .await?
+                .contains(node_id),
+            "Unsigned collector report conflicts with a known node identity"
+        );
+
         let fleet_dir = self.config.data_dir.join("telemetry-fleet");
         tokio::fs::create_dir_all(&fleet_dir)
             .await
@@ -339,9 +383,9 @@ impl RpcHandler {
         let mut nodes: Vec<serde_json::Value> = Vec::new();
 
         // ── Trusted federation nodes ─────────────────────────────────────
-        let fed_nodes = crate::federation::load_nodes(&self.config.data_dir)
-            .await
-            .unwrap_or_default();
+        let fed_nodes = crate::federation::load_nodes(&self.config.data_dir).await?;
+        let mut authoritative = federation_ids(&self.config.data_dir).await?;
+        authoritative.extend(fed_nodes.iter().map(|n| n.did.clone()));
         for n in fed_nodes
             .iter()
             .filter(|n| n.trust_level == crate::federation::TrustLevel::Trusted)
@@ -352,20 +396,19 @@ impl RpcHandler {
                     (Some(u), Some(t)) if t > 0 => {
                         serde_json::json!((u as f64 / t as f64 * 100.0).round())
                     }
-                    _ => serde_json::json!(0),
+                    _ => serde_json::Value::Null,
                 }
             };
             let apps = state.map(|s| s.apps.as_slice()).unwrap_or(&[]);
             let reported_at = state
                 .map(|s| s.timestamp.clone())
-                .or_else(|| n.last_seen.clone())
-                .unwrap_or_else(|| n.added_at.clone());
+                .or_else(|| n.last_seen.clone());
 
             let mut report = serde_json::json!({
                 "node_id": n.did,
                 "node_name": state.and_then(|s| s.node_name.clone()).or_else(|| n.name.clone()),
-                "uptime_secs": state.and_then(|s| s.uptime_secs).unwrap_or(0),
-                "cpu_pct": state.and_then(|s| s.cpu_usage_percent).map(|v| v.round()).unwrap_or(0.0),
+                "uptime_secs": state.and_then(|s| s.uptime_secs),
+                "cpu_pct": state.and_then(|s| s.cpu_usage_percent).filter(|v| v.is_finite() && (0.0..=100.0).contains(v)).map(|v| v.round()),
                 "mem_pct": pct(state.and_then(|s| s.mem_used_bytes), state.and_then(|s| s.mem_total_bytes)),
                 "disk_pct": pct(state.and_then(|s| s.disk_used_bytes), state.and_then(|s| s.disk_total_bytes)),
                 "container_count": apps.len(),
@@ -379,6 +422,7 @@ impl RpcHandler {
                 "reported_at": reported_at,
                 "trust_level": n.trust_level.to_string(),
                 "source": "federation",
+                "identity_authenticated": true,
             });
             annotate_fleet_report(&mut report);
             nodes.push(report);
@@ -401,10 +445,21 @@ impl RpcHandler {
 
                 match tokio::fs::read_to_string(entry.path()).await {
                     Ok(data) => match serde_json::from_str::<serde_json::Value>(&data) {
-                        Ok(mut report) => {
+                        Ok(report) => {
+                            if let Ok(mut report) =
+                                collector_report(report, name.strip_suffix(".json"))
+                            {
+                                let id = report["node_id"]
+                                    .as_str()
+                                    .expect("validated collector identity");
+                                // Include every relationship in this exclusion, so an unsigned
+                                // claim cannot undo observer/untrusted Fleet exclusions either.
+                                if !authoritative.contains(id) {
                                     annotate_fleet_report(&mut report);
                                     nodes.push(report);
                                 }
+                            }
+                        }
                         Err(e) => {
                             warn!(file = %name, error = %e, "Skipping corrupt fleet report");
                         }
@@ -450,6 +505,14 @@ impl RpcHandler {
             anyhow::bail!("Invalid node_id");
         }
 
+        if federation_ids(&self.config.data_dir)
+            .await?
+            .contains(node_id)
+        {
+            return Ok(serde_json::json!({"node_id":node_id,"entries":[],"count":0,
+                "history_available":false,"reason":"collector_history_not_authoritative"}));
+        }
+
         let history_path = self
             .config
             .data_dir
@@ -461,8 +524,15 @@ impl RpcHandler {
             Err(_) => Vec::new(),
         };
 
+        let history: Vec<_> = history
+            .into_iter()
+            .filter_map(|report| collector_report(report, Some(node_id)).ok())
+            .collect();
         Ok(serde_json::json!({
             "node_id": node_id,
+            "history_available": true,
+            "source": "collector",
+            "identity_authenticated": false,
             "entries": history,
             "count": history.len(),
         }))
@@ -476,6 +546,7 @@ impl RpcHandler {
             return Ok(serde_json::json!({ "alerts": [] }));
         }
 
+        let authoritative = federation_ids(&self.config.data_dir).await?;
         let mut all_alerts: Vec<serde_json::Value> = Vec::new();
         let mut entries = tokio::fs::read_dir(&fleet_dir)
             .await
@@ -498,22 +569,33 @@ impl RpcHandler {
                 Err(_) => continue,
             };
 
+            let report = match collector_report(report, name.strip_suffix(".json")) {
+                Ok(report) => report,
+                Err(_) => continue,
+            };
             let node_id = report
                 .get("node_id")
                 .and_then(|v| v.as_str())
                 .unwrap_or("unknown")
                 .to_string();
 
+            if authoritative.contains(&node_id) {
+                continue;
+            }
+
             if let Some(alerts) = report.get("recent_alerts").and_then(|v| v.as_array()) {
                 for alert in alerts {
                     let mut enriched = alert.clone();
                     if let Some(obj) = enriched.as_object_mut() {
                         obj.insert("node_id".to_string(), serde_json::json!(node_id));
-                    }
+                        obj.insert("source".into(), serde_json::json!("collector"));
+                        obj.insert("trust_level".into(), serde_json::json!("unverified"));
+                        obj.insert("identity_authenticated".into(), serde_json::json!(false));
                         all_alerts.push(enriched);
                     }
                 }
             }
+        }
 
         // Sort by timestamp descending (most recent first)
         all_alerts.sort_by(|a, b| {
@@ -561,7 +643,7 @@ fn annotate_fleet_report(report: &mut serde_json::Value) {
     let is_online = reported
         .map(|dt| {
             let age = chrono::Utc::now().signed_duration_since(dt);
-            age.num_minutes() < 30
+            age.num_seconds() >= -60 && age.num_seconds() < 1800
         })
         .unwrap_or(false);
 
@@ -569,7 +651,9 @@ fn annotate_fleet_report(report: &mut serde_json::Value) {
         .map(|dt| {
             let age = chrono::Utc::now().signed_duration_since(dt);
             let mins = age.num_minutes();
-            if mins < 1 {
+            if age.num_seconds() < -60 {
+                "unknown (clock ahead)".to_string()
+            } else if mins < 1 {
                 "just now".to_string()
             } else if mins < 60 {
                 format!("{}m ago", mins)
@@ -586,3 +670,181 @@ fn annotate_fleet_report(report: &mut serde_json::Value) {
         obj.insert("last_seen".to_string(), serde_json::json!(last_seen));
     }
 }
+
+#[cfg(test)]
+mod collector_provenance_tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn unsigned_and_legacy_reports_cannot_assign_their_own_trust() {
+        let report = collector_report(
+            json!({"node_id":"claimed-node", "source":"federation",
+            "trust_level":"trusted", "identity_authenticated":true, "cpu_pct":0}),
+            Some("claimed-node"),
+        )
+        .unwrap();
+        assert_eq!(report["source"], "collector");
+        assert_eq!(report["trust_level"], "unverified");
+        assert_eq!(report["identity_authenticated"], false);
+        assert_eq!(report["cpu_pct"], 0);
+        assert_eq!(
+            collector_report(report.clone(), Some("claimed-node")).unwrap(),
+            report
+        );
+    }
+
+    #[test]
+    fn collector_cannot_claim_another_record_identity_or_malformed_id() {
+        for value in [
+            json!(null),
+            json!([]),
+            json!({"node_id":"other"}),
+            json!({"node_id":"../escape"}),
+            json!({"node_id":"bad\nidentity"}),
+            json!({"node_id":"claimed-node-history"}),
+        ] {
+            assert!(collector_report(value, Some("claimed-node")).is_err());
+        }
+    }
+
+    #[test]
+    fn collector_history_suffix_cannot_overwrite_another_nodes_history() {
+        assert!(collector_report(json!({"node_id":"node-history"}), Some("node-history")).is_err());
+        assert!(collector_report(json!({"node_id":"node-history"}), None).is_err());
+    }
+
+    #[tokio::test]
+    async fn fleet_reads_do_not_promote_old_collector_spoofs_or_history() {
+        let data = tempfile::tempdir().unwrap();
+        let peer = serde_json::from_value(json!({"did":"known-node", "pubkey":"00".repeat(32),
+            "onion":format!("{}.onion", "a".repeat(56)), "trust_level":"trusted", "added_at":"now"})).unwrap();
+        let observer =
+            serde_json::from_value(json!({"did":"observer-node", "pubkey":"11".repeat(32),
+            "onion":format!("{}.onion", "a".repeat(56)), "trust_level":"observer", "added_at":"now"}))
+            .unwrap();
+        crate::federation::save_nodes(data.path(), &[peer, observer])
+            .await
+            .unwrap();
+        let mut config = crate::config::Config::default();
+        config.data_dir = data.path().to_path_buf();
+        let handler = RpcHandler::new(
+            config,
+            std::sync::Arc::new(crate::state::StateManager::new()),
+            std::sync::Arc::new(crate::monitoring::MetricsStore::new()),
+            crate::session::SessionStore::new_for_tests(data.path().join("sessions.json")),
+            None,
+            None,
+        )
+        .await
+        .unwrap();
+        let root = data.path().join("telemetry-fleet");
+        tokio::fs::create_dir_all(&root).await.unwrap();
+        let spoof = json!({"node_id":"known-node", "source":"federation", "trust_level":"trusted",
+            "identity_authenticated":true, "version":"spoof", "reported_at":"2026-10-07T00:00:00Z",
+            "recent_alerts":[{"message":"spoofed alert", "source":"federation", "identity_authenticated":true}]});
+        tokio::fs::write(root.join("known-node.json"), spoof.to_string())
+            .await
+            .unwrap();
+        tokio::fs::write(
+            root.join("known-node-history.json"),
+            json!([spoof.clone()]).to_string(),
+        )
+        .await
+        .unwrap();
+        assert!(handler
+            .handle_telemetry_ingest(Some(spoof.clone()))
+            .await
+            .is_err());
+        let status = handler.handle_telemetry_fleet_status().await.unwrap();
+        let nodes = status["nodes"].as_array().unwrap();
+        assert_eq!(nodes.len(), 1);
+        assert_eq!(nodes[0]["source"], "federation");
+        assert_eq!(nodes[0]["identity_authenticated"], true);
+        assert_ne!(nodes[0]["version"], "spoof");
+        let history = handler
+            .handle_telemetry_fleet_node_history(Some(json!({"node_id":"known-node"})))
+            .await
+            .unwrap();
+        assert_eq!(history["history_available"], false);
+        assert_eq!(history["count"], 0);
+        assert!(
+            handler.handle_telemetry_fleet_alerts().await.unwrap()["alerts"]
+                .as_array()
+                .unwrap()
+                .is_empty()
+        );
+        // Display dedup collapses the shared onion, but unsigned reports must
+        // still be excluded for BOTH raw identities, including the observer.
+        let ids = federation_ids(data.path()).await.unwrap();
+        assert!(ids.contains("known-node") && ids.contains("observer-node"));
+        let mut observer_spoof = spoof.clone();
+        observer_spoof["node_id"] = json!("observer-node");
+        tokio::fs::write(root.join("observer-node.json"), observer_spoof.to_string())
+            .await
+            .unwrap();
+        assert!(handler
+            .handle_telemetry_ingest(Some(observer_spoof))
+            .await
+            .is_err());
+        let status = handler.handle_telemetry_fleet_status().await.unwrap();
+        assert!(status["nodes"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .all(|node| node["source"] == "federation"));
+        assert!(
+            handler.handle_telemetry_fleet_alerts().await.unwrap()["alerts"]
+                .as_array()
+                .unwrap()
+                .is_empty()
+        );
+        let observer_history = handler
+            .handle_telemetry_fleet_node_history(Some(json!({"node_id":"observer-node"})))
+            .await
+            .unwrap();
+        assert_eq!(observer_history["history_available"], false);
+        let mut independent = spoof;
+        independent["node_id"] = json!("independent");
+        handler
+            .handle_telemetry_ingest(Some(independent))
+            .await
+            .unwrap();
+        let status = handler.handle_telemetry_fleet_status().await.unwrap();
+        let collector = status["nodes"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .find(|v| v["node_id"] == "independent")
+            .unwrap();
+        assert_eq!(collector["source"], "collector");
+        assert_eq!(collector["identity_authenticated"], false);
+        let alerts = handler.handle_telemetry_fleet_alerts().await.unwrap();
+        assert_eq!(alerts["alerts"][0]["source"], "collector");
+        assert_eq!(alerts["alerts"][0]["identity_authenticated"], false);
+        // Corrupt authoritative state must fail closed, not turn collector
+        // claims into the fallback representation of known relationships.
+        let nodes_path = data.path().join("federation").join("nodes.json");
+        tokio::fs::write(&nodes_path, b"{broken-authoritative-store")
+            .await
+            .unwrap();
+        assert!(federation_ids(data.path()).await.is_err());
+        assert!(handler.handle_telemetry_fleet_status().await.is_err());
+        assert!(handler.handle_telemetry_fleet_alerts().await.is_err());
+        assert!(handler
+            .handle_telemetry_fleet_node_history(Some(json!({"node_id":"independent"})))
+            .await
+            .is_err());
+        assert!(handler
+            .handle_telemetry_ingest(Some(
+                json!({"node_id":"new-claim", "version":"spoof", "reported_at":"now"})
+            ))
+            .await
+            .is_err());
+        assert!(!root.join("new-claim.json").exists());
+        assert_eq!(
+            tokio::fs::read(&nodes_path).await.unwrap(),
+            b"{broken-authoritative-store"
+        );
+    }
+}

core/archipelago/src/api/rpc/bitcoin.rs

@@ -136,7 +136,7 @@ impl RpcHandler {
     /// ~30% of UI calls error out even though the node is perfectly healthy.
     /// With retry + backoff, the UI sees a uniform slow-but-successful
     /// response instead of intermittent failures.
-    async fn bitcoin_rpc_call<T: serde::de::DeserializeOwned>(
+    pub(in crate::api::rpc) async fn bitcoin_rpc_call<T: serde::de::DeserializeOwned>(
         &self,
         client: &reqwest::Client,
         method: &str,

core/archipelago/src/api/rpc/content_tests.rs

@@ -0,0 +1,435 @@
+use super::*;
+
+#[test]
+fn first_and_cached_paid_downloads_have_the_same_client_payload_contract() {
+    use base64::Engine;
+    for paid in [0, 1] {
+        let response = paid_content_response(&[0, 255, 123], "application/octet-stream", paid);
+        assert_eq!(response["data"], response["data_base64"]);
+        assert_eq!(
+            base64::engine::general_purpose::STANDARD
+                .decode(response["data"].as_str().unwrap())
+                .unwrap(),
+            [0, 255, 123]
+        );
+        assert_eq!(response["size"], 3);
+        assert_eq!(response["size_bytes"], 3);
+        assert_eq!(response["paid_sats"], paid);
+        assert_eq!(response["owned"], true);
+    }
+}
+
+#[tokio::test]
+async fn files_copy_routes_media_and_sanitizes_the_filename() {
+    let dir = tempfile::tempdir().unwrap();
+    tokio::fs::create_dir(dir.path().join("filebrowser"))
+        .await
+        .unwrap();
+    for (mime, folder) in [
+        ("image/png", "Photos"),
+        ("video/mp4", "Photos"),
+        ("audio/mpeg", "Music"),
+        ("text/plain", "Documents"),
+    ] {
+        crate::content_owned::record_purchase(
+            dir.path(),
+            "seller.onion",
+            "id",
+            "../name #?.bin",
+            mime,
+            b"paid",
+            1,
+            "cashu",
+            "now",
+        )
+        .await
+        .unwrap();
+        let item = crate::content_owned::list_owned_checked(dir.path())
+            .await
+            .unwrap()
+            .remove(0);
+        let relative = file_cached_purchase_in_files(dir.path(), &item)
+            .await
+            .unwrap();
+        assert!(relative.starts_with(&format!("{folder}/name #?")));
+        assert_eq!(
+            tokio::fs::read(dir.path().join("filebrowser").join(relative))
+                .await
+                .unwrap(),
+            b"paid"
+        );
+    }
+}
+
+#[tokio::test]
+async fn unavailable_files_storage_is_reported_without_creating_a_fake_installation() {
+    let dir = tempfile::tempdir().unwrap();
+    crate::content_owned::record_purchase(
+        dir.path(),
+        "seller.onion",
+        "id",
+        "name",
+        "text/plain",
+        b"bytes",
+        1,
+        "cashu",
+        "now",
+    )
+    .await
+    .unwrap();
+    let item = crate::content_owned::list_owned_checked(dir.path())
+        .await
+        .unwrap()
+        .remove(0);
+    assert!(file_cached_purchase_in_files(dir.path(), &item)
+        .await
+        .is_err());
+    assert!(!dir.path().join("filebrowser").exists());
+}
+
+#[test]
+fn seller_errors_are_bounded_printable_and_identified_as_peer_text() {
+    let status = reqwest::StatusCode::SERVICE_UNAVAILABLE;
+    let message = seller_error_message(status, r#"{"error":"Cannot read file\n\u0000"}"#);
+    assert!(message.starts_with("Seller response (503"));
+    assert!(message.ends_with("Cannot read file"));
+    assert!(!message.contains('\n') && !message.contains('\0'));
+    let body = serde_json::json!({"error": "é".repeat(1000)}).to_string();
+    assert!(seller_error_message(status, &body).chars().count() < 300);
+    for body in ["not JSON", r#"{"error": 7}"#, r#"{"error":"   "}"#] {
+        assert_eq!(
+            seller_error_message(status, body),
+            "Peer returned an error (503 Service Unavailable)."
+        );
+    }
+}
+
+#[tokio::test]
+async fn known_purchase_never_becomes_a_new_spend_when_cache_or_index_is_unavailable() {
+    let dir = tempfile::tempdir().unwrap();
+    assert!(
+        existing_paid_content(dir.path(), "seller.onion", "id", None, false)
+            .await
+            .unwrap()
+            .is_none()
+    );
+    crate::content_owned::record_purchase(
+        dir.path(),
+        "seller.onion",
+        "id",
+        "file.txt",
+        "text/plain",
+        b"paid",
+        1,
+        "cashu",
+        "now",
+    )
+    .await
+    .unwrap();
+    for (id, filename) in [("id", None), ("duplicate-id", Some("/file.txt"))] {
+        let cached = existing_paid_content(dir.path(), "seller.onion", id, filename, false)
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(cached["paid_sats"], 0);
+        assert_eq!(cached["already_owned"], true);
+        assert_eq!(cached["data"], "cGFpZA==");
+    }
+    assert!(
+        existing_paid_content(dir.path(), "different.onion", "id", None, false)
+            .await
+            .unwrap()
+            .is_none()
+    );
+    tokio::fs::remove_file(dir.path().join("purchased-content/seller.onion/id"))
+        .await
+        .unwrap();
+    assert!(
+        existing_paid_content(dir.path(), "seller.onion", "id", None, false)
+            .await
+            .unwrap_err()
+            .to_string()
+            .contains("No new payment")
+    );
+    tokio::fs::write(dir.path().join("purchased-content/owned.json"), b"damaged")
+        .await
+        .unwrap();
+    assert!(
+        existing_paid_content(dir.path(), "seller.onion", "other-id", None, false)
+            .await
+            .unwrap_err()
+            .to_string()
+            .contains("no new payment")
+    );
+    assert_eq!(
+        tokio::fs::read(dir.path().join("purchased-content/owned.json"))
+            .await
+            .unwrap(),
+        b"damaged"
+    );
+}
+
+#[tokio::test]
+async fn inline_download_limits_known_and_chunked_bodies_without_draining_them() {
+    use futures_util::StreamExt;
+    use std::sync::{
+        atomic::{AtomicUsize, Ordering},
+        Arc,
+    };
+    let response: reqwest::Response = hyper::Response::new("small").into();
+    assert!(bounded_content_bytes(response, 4).await.is_err());
+    let response: reqwest::Response = hyper::Response::new("small").into();
+    assert_eq!(bounded_content_bytes(response, 5).await.unwrap(), b"small");
+    let consumed = Arc::new(AtomicUsize::new(0));
+    let counter = consumed.clone();
+    let chunks = futures_util::stream::iter(0..1000).map(move |_| {
+        counter.fetch_add(1, Ordering::SeqCst);
+        Ok::<_, std::io::Error>(bytes::Bytes::from_static(b"abc"))
+    });
+    let body = reqwest::Body::wrap_stream(chunks);
+    let response: reqwest::Response = hyper::Response::new(body).into();
+    assert!(bounded_content_bytes(response, 4).await.is_err());
+    assert_eq!(consumed.load(Ordering::SeqCst), 2);
+}
+
+#[tokio::test]
+async fn onchain_delivery_streams_to_owned_cache_and_preserves_incomplete_recovery() {
+    use tokio::io::AsyncReadExt;
+    let dir = tempfile::tempdir().unwrap();
+    let response: reqwest::Response = hyper::Response::builder()
+        .header("content-length", "2097152")
+        .body(hyper::Body::from(vec![71u8; 2 * 1024 * 1024]))
+        .unwrap()
+        .into();
+    let item = cache_peer_response(
+        dir.path(),
+        "seller.onion",
+        "film",
+        "film.mp4",
+        "video/mp4",
+        1,
+        "onchain",
+        response,
+    )
+    .await
+    .unwrap();
+    assert!(item.download_complete);
+    assert_eq!(item.ecash_backend, "onchain");
+    let (_, mut file) = crate::content_owned::open_owned(dir.path(), "seller.onion", "film")
+        .await
+        .unwrap()
+        .unwrap();
+    let mut bytes = Vec::new();
+    file.read_to_end(&mut bytes).await.unwrap();
+    assert_eq!(bytes, vec![71u8; 2 * 1024 * 1024]);
+    let reply = cached_purchase_response(dir.path(), "seller.onion", "film", true, 0)
+        .await
+        .unwrap();
+    assert_eq!(reply["owned"], true);
+    assert!(reply.get("data").is_none());
+
+    let truncated: reqwest::Response = hyper::Response::builder()
+        .header("content-length", "100")
+        .body(hyper::Body::wrap_stream(futures_util::stream::iter([
+            Ok(bytes::Bytes::from_static(b"short")),
+            Err(std::io::Error::new(
+                std::io::ErrorKind::UnexpectedEof,
+                "connection closed before delivery completed",
+            )),
+        ])))
+        .unwrap()
+        .into();
+    assert!(cache_peer_response(
+        dir.path(),
+        "seller.onion",
+        "interrupted",
+        "film.mp4",
+        "video/mp4",
+        1,
+        "onchain",
+        truncated
+    )
+    .await
+    .is_err());
+    let entries = crate::content_owned::list_owned_checked(dir.path())
+        .await
+        .unwrap();
+    assert!(
+        !entries
+            .iter()
+            .find(|item| item.content_id == "interrupted")
+            .unwrap()
+            .download_complete
+    );
+    assert!(
+        existing_paid_content(dir.path(), "seller.onion", "interrupted", None, true)
+            .await
+            .is_err()
+    );
+}
+
+#[test]
+fn share_creation_stays_hidden_without_explicit_visibility_and_rejects_invalid_policy() {
+    let empty = serde_json::json!({});
+    assert!(matches!(
+        parse_content_availability(&empty, "nobody").unwrap(),
+        Availability::Nobody
+    ));
+    assert!(matches!(
+        parse_content_access(&empty).unwrap(),
+        AccessControl::Free
+    ));
+    for invalid in [
+        serde_json::json!({"access":null}),
+        serde_json::json!({"access":"paid","price_sats":0}),
+        serde_json::json!({"access":"paid","price_sats":1,"accepted_methods":["unsupported"]}),
+        serde_json::json!({"access":"paid","price_sats":1,"accepted_methods":"ecash"}),
+    ] {
+        assert!(parse_content_access(&invalid).is_err());
+    }
+    let paid = serde_json::json!({"access":"paid","price_sats":1,"accepted_methods":["ecash"],"availability":"all_peers"});
+    assert!(matches!(
+        parse_content_access(&paid).unwrap(),
+        AccessControl::Paid { price_sats: 1, .. }
+    ));
+    assert!(matches!(
+        parse_content_availability(&paid, "nobody").unwrap(),
+        Availability::AllPeers
+    ));
+}
+
+#[tokio::test]
+async fn repeated_share_returns_stable_id_and_complete_policy() {
+    let dir = tempfile::tempdir().unwrap();
+    let mut config = crate::config::Config::default();
+    config.data_dir = dir.path().to_path_buf();
+    config.dev_mode = false;
+    let sessions = crate::session::SessionStore::new_for_tests(dir.path().join("sessions.json"));
+    let handler = RpcHandler::new(
+        config,
+        std::sync::Arc::new(crate::state::StateManager::new()),
+        std::sync::Arc::new(crate::monitoring::MetricsStore::new()),
+        sessions,
+        None,
+        None,
+    )
+    .await
+    .unwrap();
+    let first = handler
+        .handle_content_publish(Some(serde_json::json!({
+            "filename":"film.mp4", "access":"paid", "price_sats":1,
+            "accepted_methods":["ecash"], "availability":"nobody"
+        })))
+        .await
+        .unwrap();
+    let second = handler
+        .handle_content_publish(Some(serde_json::json!({
+            "filename":"film.mp4", "access":"paid", "price_sats":2,
+            "accepted_methods":["lightning"], "availability":"nobody"
+        })))
+        .await
+        .unwrap();
+    assert_eq!(first["item"]["id"], second["item"]["id"]);
+    let catalog = content_server::load_catalog(dir.path()).await.unwrap();
+    assert_eq!(catalog.items.len(), 1);
+    let item = &catalog.items[0];
+    assert_eq!(second["item"]["id"].as_str(), Some(item.id.as_str()));
+    assert!(
+        matches!(&item.access, AccessControl::Paid { price_sats: 2, accepted } if accepted == &["lightning"])
+    );
+    assert!(matches!(item.availability, Availability::Nobody));
+    assert!(handler
+        .handle_content_configure(Some(serde_json::json!({
+            "id":item.id, "access":"free"
+        })))
+        .await
+        .is_err());
+    assert!(matches!(
+        content_server::load_catalog(dir.path())
+            .await
+            .unwrap()
+            .items[0]
+            .access,
+        AccessControl::Paid { price_sats: 2, .. }
+    ));
+}
+
+#[tokio::test]
+async fn legacy_payment_routes_refuse_fresh_spending_but_preserve_paid_cache() {
+    let data = tempfile::tempdir().unwrap();
+    let mut config = crate::config::Config::default();
+    config.data_dir = data.path().to_path_buf();
+    let handler = RpcHandler::new(
+        config,
+        std::sync::Arc::new(crate::state::StateManager::new()),
+        std::sync::Arc::new(crate::monitoring::MetricsStore::new()),
+        crate::session::SessionStore::new_for_tests(data.path().join("sessions.json")),
+        None,
+        None,
+    )
+    .await
+    .unwrap();
+    let onion = format!("{}.onion", "a".repeat(56));
+    for method in ["cashu", "fedimint", "auto"] {
+        let error = handler
+            .handle_content_download_peer_paid(Some(serde_json::json!({
+                "onion": onion, "content_id": "file", "price_sats": 1,
+                "method": method, "cache_only": true
+            })))
+            .await
+            .unwrap_err();
+        assert!(
+            error.to_string().contains("No payment was sent"),
+            "{error:#}"
+        );
+    }
+    assert!(handler
+        .handle_content_request_invoice(None)
+        .await
+        .unwrap_err()
+        .to_string()
+        .contains("saved Lightning purchase flow"));
+    assert!(handler
+        .handle_content_request_onchain(None)
+        .await
+        .unwrap_err()
+        .to_string()
+        .contains("saved Bitcoin purchase flow"));
+    assert!(!data.path().join("wallet").exists());
+    crate::content_owned::record_purchase(
+        data.path(),
+        &onion,
+        "file",
+        "paid.txt",
+        "text/plain",
+        b"previously paid",
+        1,
+        "fedimint",
+        "2026-10-01T00:00:00Z",
+    )
+    .await
+    .unwrap();
+    for cache_only in [true, false] {
+        let result = handler
+            .handle_content_download_peer_paid(Some(serde_json::json!({
+                "onion": onion, "content_id": "file", "price_sats": 1,
+                "method": "fedimint", "cache_only": cache_only
+            })))
+            .await
+            .unwrap();
+        assert_eq!(result["paid_sats"], 0);
+        assert_eq!(result["already_owned"], true);
+        if cache_only {
+            assert_eq!(result["owned"], true);
+        } else {
+            use base64::Engine;
+            assert_eq!(
+                base64::engine::general_purpose::STANDARD
+                    .decode(result["data"].as_str().unwrap())
+                    .unwrap(),
+                b"previously paid"
+            );
+        }
+    }
+    assert!(!data.path().join("wallet").exists());
+}

core/archipelago/src/api/rpc/dispatcher.rs

@@ -132,6 +132,9 @@ impl RpcHandler {
             "lnd.newaddress" => self.handle_lnd_newaddress().await,
             "lnd.sendcoins" => self.handle_lnd_sendcoins(params).await,
             "lnd.estimatefee" => self.handle_lnd_estimatefee(params).await,
+            "lnd.bump-quote" => self.handle_lnd_bump_quote(params).await,
+            "lnd.bump-submit" => self.handle_lnd_bump_submit(params).await,
+            "lnd.bump-status" => self.handle_lnd_bump_status(params).await,
             "lnd.createinvoice" => self.handle_lnd_createinvoice(params).await,
             "lnd.invoicestatus" => self.handle_lnd_invoicestatus(params).await,
             "lnd.payinvoice" => self.handle_lnd_payinvoice(params).await,
@@ -319,6 +322,8 @@ impl RpcHandler {
             // Content catalog management
             "content.list-mine" => self.handle_content_list_mine().await,
             "content.add" => self.handle_content_add(params).await,
+            "content.publish" => self.handle_content_publish(params).await,
+            "content.configure" => self.handle_content_configure(params).await,
             "content.remove" => self.handle_content_remove(params).await,
             "content.set-pricing" => self.handle_content_set_pricing(params).await,
             "content.set-availability" => self.handle_content_set_availability(params).await,
@@ -327,6 +332,43 @@ impl RpcHandler {
             "content.download-peer-paid" => self.handle_content_download_peer_paid(params).await,
             "content.indeehub-projects" => self.handle_content_indeehub_projects().await,
             "content.browse-all-peers" => self.handle_content_browse_all_peers().await,
+            "content.playback-handle" => self.handle_playback_handle(params, session_token).await,
+            "content.playback-prepare" => self.handle_playback_prepare(params, session_token).await,
+            "content.playback-start" => self.handle_playback_start(params, session_token).await,
+            "content.playback-status" => self.handle_playback_status(params, session_token).await,
+            "content.rental-purchase" => self.handle_content_rental_purchase(params).await,
+            "content.onchain-cancel" => self.handle_onchain_operation(params, "cancel").await,
+            "content.onchain-attempt" => self.handle_onchain_operation(params, "lookup").await,
+            "content.onchain-create" => self.handle_onchain_operation(params, "create").await,
+            "content.onchain-expose" => self.handle_onchain_operation(params, "expose").await,
+            "content.onchain-prepare" => self.handle_onchain_operation(params, "prepare").await,
+            "content.onchain-pay" => self.handle_onchain_operation(params, "pay").await,
+            "content.onchain-recover" => self.handle_onchain_operation(params, "status").await,
+            "content.onchain-download" => self.handle_onchain_operation(params, "download").await,
+            "content.invoice-pay" => self.handle_lightning_operation(params, "pay").await,
+            "content.invoice-download" => self.handle_lightning_operation(params, "download").await,
+            "content.invoice-attempt" => self.handle_lightning_operation(params, "lookup").await,
+            "content.invoice-retry-native" => {
+                self.handle_lightning_operation(params, "retry").await
+            }
+            "content.invoice-create" => self.handle_lightning_operation(params, "create").await,
+            "content.invoice-recover" => self.handle_lightning_operation(params, "status").await,
+            "content.invoice-cancel" => self.handle_lightning_operation(params, "cancel").await,
+            "content.purchase" => self.handle_content_purchase(params).await,
+            "content.cancel-purchase" => self.handle_content_cancel_purchase(params).await,
+            "content.payment-status" => self.handle_content_payment_status(params).await,
+            "media.registration.context" => {
+                self.handle_media_registration_context(params.unwrap_or_default())
+                    .await
+            }
+            "media.registration.prepare" => {
+                self.handle_media_registration_prepare(params.unwrap_or_default())
+                    .await
+            }
+            "media.registration.resolve" => {
+                self.handle_media_registration_resolve(params.unwrap_or_default())
+                    .await
+            }
             "content.owned-list" => self.handle_content_owned_list().await,
             "content.owned-get" => self.handle_content_owned_get(params).await,
             "content.request-invoice" => self.handle_content_request_invoice(params).await,

core/archipelago/src/api/rpc/federation/handlers.rs

@@ -7,6 +7,8 @@ use crate::mesh;
 use crate::network::dwn_store::DwnStore;
 use crate::nostr_handshake;
 use anyhow::Result;
+use futures_util::stream::{FuturesUnordered, StreamExt};
+use std::sync::Arc;
 use tracing::{debug, info, warn};
 
 const FEDERATION_PROTOCOL: &str = "https://archipelago.dev/protocols/federation/v1";
@@ -460,37 +462,65 @@ impl RpcHandler {
         let identity_dir = self.config.data_dir.join("identity");
         let node_identity = identity::NodeIdentity::load_or_create(&identity_dir).await?;
 
-        let mut synced = 0u32;
-        let mut failed = 0u32;
-        let mut results = Vec::new();
+        // A dead Tor peer can take the bounded transport timeout. Serialising
+        // those waits made one bad peer block every healthy peer behind it.
+        // Keep concurrency bounded so a large federation cannot exhaust the
+        // node's sockets or overwhelm a peer, while allowing healthy peers to
+        // finish independently. Results are tagged and sorted below so the
+        // response remains stable for callers and tests.
+        const MAX_CONCURRENT_SYNCS: usize = 4;
+        let semaphore = Arc::new(tokio::sync::Semaphore::new(MAX_CONCURRENT_SYNCS));
+        let identity = Arc::new(node_identity);
+        let data_dir = self.config.data_dir.clone();
+        let mut pending = FuturesUnordered::new();
 
-        for node in &nodes {
-            if node.trust_level == TrustLevel::Untrusted {
-                continue;
+        for (index, node) in nodes
+            .into_iter()
+            .filter(|node| node.trust_level != TrustLevel::Untrusted)
+            .enumerate()
+        {
+            let data_dir = data_dir.clone();
+            let local_did = local_did.clone();
+            let identity = identity.clone();
+            let semaphore = semaphore.clone();
+            pending.push(async move {
+                let permit = semaphore
+                    .acquire_owned()
+                    .await
+                    .expect("sync semaphore lives for all pending syncs");
+                let result = federation::sync_with_peer(&data_dir, &node, &local_did, |bytes| {
+                    identity.sign(bytes)
+                })
+                .await;
+                drop(permit);
+                (index, node.did, result)
+            });
         }
 
-            let did_clone = local_did.clone();
-            match federation::sync_with_peer(&self.config.data_dir, node, &did_clone, |bytes| {
-                node_identity.sign(bytes)
-            })
-            .await
-            {
-                Ok(state) => {
-                    synced += 1;
-                    results.push(serde_json::json!({
-                        "did": node.did,
+        let mut results = Vec::new();
+        while let Some((index, did, result)) = pending.next().await {
+            let row = match result {
+                Ok(state) => serde_json::json!({
+                    "index": index,
+                    "did": did,
                     "status": "ok",
                     "apps": state.apps.len(),
-                    }));
-                }
-                Err(e) => {
-                    failed += 1;
-                    results.push(serde_json::json!({
-                        "did": node.did,
+                }),
+                Err(e) => serde_json::json!({
+                    "index": index,
+                    "did": did,
                     "status": "error",
                     "error": e.to_string(),
-                    }));
+                }),
+            };
+            results.push(row);
         }
+        results.sort_by_key(|row| row["index"].as_u64().unwrap_or(u64::MAX));
+        let synced = results.iter().filter(|row| row["status"] == "ok").count() as u32;
+        let failed = results.len() as u32 - synced;
+        for row in &mut results {
+            if let Some(object) = row.as_object_mut() {
+                object.remove("index");
             }
         }
 
@@ -572,14 +602,39 @@ impl RpcHandler {
             None
         };
 
+        // Reuse the minute collector instead of running expensive probes for
+        // every peer. An absent/stalled collector is unknown, never zero load.
+        let now = chrono::Utc::now().timestamp();
+        let latest = self
+            .metrics_store
+            .latest()
+            .await
+            .filter(|sample| (0..=180).contains(&now.saturating_sub(sample.timestamp)));
+        let metrics = latest.as_ref().map(|sample| &sample.system);
+        let uptime = tokio::fs::read_to_string("/proc/uptime")
+            .await
+            .ok()
+            .and_then(|s| s.split_whitespace().next()?.parse::<f64>().ok())
+            .filter(|v| v.is_finite() && *v >= 0.0)
+            .map(|v| v as u64);
         let state = federation::build_local_state(
             apps,
-            0.0,
-            0,
-            0,
-            0,
-            0,
-            0,
+            metrics
+                .map(|m| m.cpu_percent)
+                .filter(|v| v.is_finite() && (0.0..=100.0).contains(v)),
+            metrics
+                .filter(|m| m.mem_total_bytes > 0)
+                .map(|m| m.mem_used_bytes),
+            metrics
+                .filter(|m| m.mem_total_bytes > 0)
+                .map(|m| m.mem_total_bytes),
+            metrics
+                .filter(|m| m.disk_total_bytes > 0)
+                .map(|m| m.disk_used_bytes),
+            metrics
+                .filter(|m| m.disk_total_bytes > 0)
+                .map(|m| m.disk_total_bytes),
+            uptime,
             tor_active,
             server_name,
             nostr_npub,
@@ -1224,76 +1279,120 @@ impl RpcHandler {
             );
         }
 
+        let reply = self.prepare_peer_approval_reply(&req).await?;
+        // Persist the operator decision before transport. A relay outage must
+        // not require another approval or lose the already-authorized reply.
+        pending::decide(&self.config.data_dir, id, pending::PendingState::Approved).await?;
+        let delivered = self.deliver_peer_approval_reply(&reply).await?;
+        Ok(serde_json::json!({ "approved": true, "id": id, "delivery_pending": !delivered }))
+    }
+
+    async fn prepare_peer_approval_reply(
+        &self,
+        req: &pending::PendingPeerRequest,
+    ) -> Result<federation::handshake_delivery::ApprovalReply> {
+        use federation::handshake_delivery::{self, ApprovalReply};
+        if let Some(reply) = handshake_delivery::find(&self.config.data_dir, &req.id).await? {
+            anyhow::ensure!(
+                reply.recipient == req.from_nostr_pubkey && reply.expected_did == req.from_did,
+                "Approval recipient changed"
+            );
+            return Ok(reply);
+        }
         let (data, _) = self.state_manager.get_snapshot().await;
         let local_did = identity::did_key_from_pubkey_hex(&data.server_info.pubkey)?;
         let local_onion = data
             .server_info
             .tor_address
-            .clone()
+            .as_deref()
             .ok_or_else(|| anyhow::anyhow!("Tor address not available"))?;
-        let local_pubkey = data.server_info.pubkey.clone();
-
-        // Generate a one-shot federation invite. The code embeds OUR onion
-        // and OUR pubkey, but it leaves this box only inside the NIP-44
-        // ciphertext below.
-        let identity_dir = self.config.data_dir.join("identity");
-        let local_fips_npub = identity::fips_npub(&identity_dir).await.unwrap_or(None);
-        // Discovery/connection-request approvals admit the requester as
-        // Observer — the invite itself now carries that level, so both
-        // sides converge on Observer without post-hoc demotion.
+        let local_fips_npub = identity::fips_npub(&self.config.data_dir.join("identity"))
+            .await
+            .unwrap_or(None);
         let invite_code = federation::create_invite(
             &self.config.data_dir,
             &local_did,
-            &local_onion,
-            &local_pubkey,
+            local_onion,
+            &data.server_info.pubkey,
             local_fips_npub.as_deref(),
             TrustLevel::Observer,
         )
         .await?;
-
-        // Pre-add the requester to OUR federation list as Observer so that
-        // when their `federation.peer-joined` callback arrives over Tor we
-        // already trust their pubkey enough to accept the join. Their DID
-        // and pubkey come from the request — we'll cross-check the pubkey
-        // against the eventual peer-joined signature in the existing
-        // verification path (handlers.rs line ~365).
-        if !req.from_did.is_empty() {
-            // We don't know the requester's onion or ed25519 pubkey yet —
-            // they'll send those in the federation.peer-joined callback
-            // after they apply our invite. Until then we can't add a real
-            // FederatedNode entry. We just store the pending row as
-            // Approved so the UI shows progress, and trust the existing
-            // peer-joined handler to admit them as Observer when they call.
-            //
-            // Caveat: peer-joined currently hardcodes TrustLevel::Trusted.
-            // We override that below by demoting on success.
-            debug!(
-                requester_did = %req.from_did,
-                "Approval pending — waiting for federation.peer-joined callback over Tor"
-            );
+        handshake_delivery::stage(
+            &self.config.data_dir,
+            ApprovalReply {
+                request_id: req.id.clone(),
+                recipient: req.from_nostr_pubkey.clone(),
+                expected_did: req.from_did.clone(),
+                invite_code,
+                attempts: 0,
+                next_attempt: 0,
+            },
+        )
+        .await
     }
 
-        // Encrypt + send the invite over NIP-44 to the requester.
-        let identity_dir = self.config.data_dir.join("identity");
-        nostr_handshake::send_peer_invite(
-            &identity_dir,
-            &req.from_nostr_pubkey,
-            &invite_code,
-            &self.config.nostr_relays,
+    async fn deliver_peer_approval_reply(
+        &self,
+        reply: &federation::handshake_delivery::ApprovalReply,
+    ) -> Result<bool> {
+        let Some(claimed) = federation::handshake_delivery::claim(
+            &self.config.data_dir,
+            &reply.request_id,
+            chrono::Utc::now().timestamp(),
+        )
+        .await?
+        else {
+            return Ok(false);
+        };
+        let result = nostr_handshake::send_peer_invite(
+            &self.config.data_dir.join("identity"),
+            &claimed.recipient,
+            &claimed.invite_code,
+            &self.handshake_relays().await,
             self.config.nostr_tor_proxy.as_deref(),
         )
-        .await?;
+        .await;
+        if result.is_err() {
+            warn!(request_id = %reply.request_id, "Peer approval delivery deferred; durable retry scheduled");
+        }
+        Ok(result.is_ok())
+    }
 
-        pending::set_state(&self.config.data_dir, id, pending::PendingState::Approved).await?;
-        info!(
-            id = %id,
-            from = %req.from_nostr_pubkey,
-            "Approved peer request and shipped invite over NIP-44"
-        );
-        Ok(serde_json::json!({
-            "approved": true,
-            "id": id,
-        }))
+    /// Recover relay loss and legacy approvals without changing trust or
+    /// resurrecting a node that the operator explicitly removed.
+    pub(in crate::api::rpc) async fn retry_peer_approval_replies(&self) -> Result<()> {
+        let requests = pending::load_pending(&self.config.data_dir).await?;
+        let nodes = federation::load_nodes(&self.config.data_dir).await?;
+        let removed = federation::load_removed_dids(&self.config.data_dir).await?;
+        let cutoff = chrono::Utc::now() - chrono::Duration::days(30);
+        let mut sent = 0;
+        for req in requests {
+            if req.outbound || req.state != pending::PendingState::Approved {
+                federation::handshake_delivery::remove(&self.config.data_dir, &req.id).await?;
+                continue;
+            }
+            let expired = chrono::DateTime::parse_from_rfc3339(&req.received_at)
+                .map(|time| time < cutoff)
+                .unwrap_or(true);
+            if expired
+                || removed.contains(&req.from_did)
+                || nodes.iter().any(|node| node.did == req.from_did)
+            {
+                federation::handshake_delivery::remove(&self.config.data_dir, &req.id).await?;
+                continue;
+            }
+            if req.from_did.is_empty() || sent >= 4 {
+                continue;
+            }
+            let reply = self.prepare_peer_approval_reply(&req).await?;
+            if reply.next_attempt > chrono::Utc::now().timestamp() {
+                continue;
+            }
+            self.deliver_peer_approval_reply(&reply).await?;
+            sent += 1;
+        }
+        Ok(())
     }
 
     /// federation.reject-request — drop a pending request and, if requested,
@@ -1323,19 +1422,19 @@ impl RpcHandler {
             );
         }
 
+        pending::decide(&self.config.data_dir, id, pending::PendingState::Rejected).await?;
         if notify {
             let identity_dir = self.config.data_dir.join("identity");
             let _ = nostr_handshake::send_peer_reject(
                 &identity_dir,
                 &req.from_nostr_pubkey,
                 reason,
-                &self.config.nostr_relays,
+                &self.handshake_relays().await,
                 self.config.nostr_tor_proxy.as_deref(),
             )
             .await;
         }
 
-        pending::set_state(&self.config.data_dir, id, pending::PendingState::Rejected).await?;
         info!(id = %id, from = %req.from_nostr_pubkey, "Rejected peer request");
         Ok(serde_json::json!({ "rejected": true, "id": id }))
     }
@@ -1361,16 +1460,7 @@ impl RpcHandler {
             .and_then(|v| v.as_bool())
             .unwrap_or(true);
 
-        let req = pending::find_by_id(&self.config.data_dir, id)
-            .await?
-            .ok_or_else(|| anyhow::anyhow!("Pending request not found: {}", id))?;
-        if !req.outbound || !matches!(req.state, pending::PendingState::Sent) {
-            anyhow::bail!(
-                "Can only cancel outbound requests in Sent state (outbound={}, state={:?})",
-                req.outbound,
-                req.state
-            );
-        }
+        let req = pending::cancel_outbound(&self.config.data_dir, id).await?;
 
         if notify {
             let identity_dir = self.config.data_dir.join("identity");
@@ -1380,7 +1470,7 @@ impl RpcHandler {
                 &identity_dir,
                 &req.from_nostr_pubkey,
                 reason,
-                &self.config.nostr_relays,
+                &self.handshake_relays().await,
                 self.config.nostr_tor_proxy.as_deref(),
             )
             .await
@@ -1393,7 +1483,6 @@ impl RpcHandler {
             }
         }
 
-        pending::delete(&self.config.data_dir, id).await?;
         info!(id = %id, to = %req.from_nostr_pubkey, notified = notify, "Cancelled outbound peer request");
         Ok(serde_json::json!({ "cancelled": true, "id": id, "notified": notify }))
     }

core/archipelago/src/api/rpc/federation/handshake_tests.rs

@@ -0,0 +1,455 @@
+//! Exercise encrypted replies through a relay configured in the UI only.
+use crate::federation::pending::{self, PendingState};
+use futures_util::{SinkExt, StreamExt};
+use nostr_sdk::prelude::{nip44, Event, Keys};
+use std::sync::Arc;
+use std::time::Duration;
+
+#[tokio::test]
+async fn managed_relay_receives_approval_rejection_and_cancellation() {
+    for (operation, accepted) in [
+        ("approve", true),
+        ("reject", true),
+        ("cancel", true),
+        ("approve", false),
+        ("retry", true),
+    ] {
+        let tmp = tempfile::tempdir().unwrap();
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let relay_url = format!("ws://{}", listener.local_addr().unwrap());
+        let relay = tokio::spawn(async move {
+            let (socket, _) = listener.accept().await.unwrap();
+            let mut ws = tokio_tungstenite::accept_async(socket).await.unwrap();
+            while let Some(Ok(message)) = ws.next().await {
+                if !message.is_text() {
+                    continue;
+                }
+                let value: serde_json::Value =
+                    serde_json::from_str(message.to_text().unwrap()).unwrap();
+                if value[0] != "EVENT" {
+                    continue;
+                }
+                let event: Event = serde_json::from_value(value[1].clone()).unwrap();
+                event.verify().unwrap();
+                ws.send(tokio_tungstenite::tungstenite::Message::Text(
+                    serde_json::json!([
+                        "OK",
+                        event.id.to_hex(),
+                        accepted,
+                        "blocked: fixture rejection"
+                    ])
+                    .to_string(),
+                ))
+                .await
+                .unwrap();
+                return event;
+            }
+            panic!("relay closed without a signed event");
+        });
+        let mut config = crate::config::Config::default();
+        config.data_dir = tmp.path().to_path_buf();
+        config.nostr_relays.clear();
+        config.nostr_tor_proxy = None;
+        crate::nostr_relays::save_relays(
+            tmp.path(),
+            &crate::nostr_relays::RelayStore {
+                relays: vec![crate::nostr_relays::RelayConfig {
+                    url: relay_url,
+                    enabled: true,
+                    added_at: chrono::Utc::now().to_rfc3339(),
+                }],
+            },
+        )
+        .await
+        .unwrap();
+        let sender = Keys::parse(&"11".repeat(32)).unwrap();
+        let recipient = Keys::parse(&"22".repeat(32)).unwrap();
+        let identity_dir = tmp.path().join("identity");
+        tokio::fs::create_dir_all(&identity_dir).await.unwrap();
+        tokio::fs::write(identity_dir.join("nostr_secret"), "11".repeat(32))
+            .await
+            .unwrap();
+        tokio::fs::write(identity_dir.join("node_key"), [0x33; 32])
+            .await
+            .unwrap();
+        let state = Arc::new(crate::state::StateManager::new());
+        state
+            .mutate_data(|data| {
+                data.server_info.pubkey = "33".repeat(32);
+                data.server_info.tor_address = Some(format!("{}.onion", "a".repeat(56)));
+            })
+            .await;
+        let handler = crate::api::rpc::RpcHandler::new(
+            config,
+            state,
+            Arc::new(crate::monitoring::MetricsStore::new()),
+            crate::session::SessionStore::new_for_tests(tmp.path().join("sessions.json")),
+            None,
+            None,
+        )
+        .await
+        .unwrap();
+        let row = if operation == "cancel" {
+            pending::insert_outbound(
+                tmp.path(),
+                recipient.public_key().to_hex(),
+                String::new(),
+                crate::identity::did_key_from_pubkey_hex(&"44".repeat(32)).unwrap(),
+                None,
+                None,
+            )
+            .await
+            .unwrap()
+        } else {
+            pending::insert_inbound(
+                tmp.path(),
+                recipient.public_key().to_hex(),
+                String::new(),
+                crate::identity::did_key_from_pubkey_hex(&"44".repeat(32)).unwrap(),
+                None,
+                None,
+            )
+            .await
+            .unwrap()
+            .unwrap()
+        };
+        if operation == "retry" {
+            pending::decide(tmp.path(), &row.id, PendingState::Approved)
+                .await
+                .unwrap();
+        }
+        let params = Some(serde_json::json!({"id": row.id, "notify": true}));
+        let action = async {
+            match operation {
+                "approve" => handler.handle_federation_approve_request(params).await,
+                "reject" => handler.handle_federation_reject_request(params).await,
+                "retry" => handler
+                    .retry_peer_approval_replies()
+                    .await
+                    .map(|_| serde_json::json!({"ok": true})),
+                _ => handler.handle_federation_cancel_request(params).await,
+            }
+        };
+        let outcome = tokio::time::timeout(Duration::from_secs(20), action)
+            .await
+            .unwrap();
+        assert_eq!(outcome.is_ok(), accepted || operation == "approve");
+        let event = tokio::time::timeout(Duration::from_secs(5), relay)
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(event.pubkey, sender.public_key());
+        let plaintext =
+            nip44::decrypt(recipient.secret_key(), &event.pubkey, &event.content).unwrap();
+        let message: serde_json::Value = serde_json::from_str(&plaintext).unwrap();
+        let expected = match operation {
+            "approve" | "retry" => "peer-invite",
+            "reject" => "peer-reject",
+            _ => "peer-cancel",
+        };
+        assert_eq!(message["type"], expected);
+        let saved = pending::find_by_id(tmp.path(), &row.id).await.unwrap();
+        if !accepted {
+            assert_eq!(
+                saved.unwrap().state,
+                if operation == "approve" {
+                    PendingState::Approved
+                } else {
+                    PendingState::Pending
+                }
+            );
+            if operation == "approve" {
+                assert_eq!(outcome.unwrap()["delivery_pending"], true);
+                let durable = crate::federation::handshake_delivery::find(tmp.path(), &row.id)
+                    .await
+                    .unwrap()
+                    .unwrap();
+                assert_eq!(durable.recipient, recipient.public_key().to_hex());
+                assert_eq!(durable.attempts, 1);
+            }
+            assert!(crate::federation::load_nodes(tmp.path())
+                .await
+                .unwrap()
+                .is_empty());
+            continue;
+        }
+        match operation {
+            "approve" | "retry" => {
+                assert_eq!(saved.unwrap().state, PendingState::Approved);
+                let first = crate::federation::handshake_delivery::find(tmp.path(), &row.id)
+                    .await
+                    .unwrap()
+                    .unwrap();
+                assert_eq!(first.attempts, 1);
+                // Concurrent/background polling honors the persisted backoff.
+                handler.retry_peer_approval_replies().await.unwrap();
+                let second = crate::federation::handshake_delivery::find(tmp.path(), &row.id)
+                    .await
+                    .unwrap()
+                    .unwrap();
+                assert_eq!(second.attempts, 1);
+                assert_eq!(first.invite_code, second.invite_code);
+                let invite =
+                    crate::federation::parse_invite(message["invite_code"].as_str().unwrap())
+                        .unwrap();
+                assert_eq!(invite.trust_level, crate::federation::TrustLevel::Observer);
+                assert!(!event.content.contains(".onion"));
+            }
+            "reject" => assert_eq!(saved.unwrap().state, PendingState::Rejected),
+            _ => assert!(saved.is_none()),
+        }
+    }
+}
+
+#[tokio::test]
+async fn federation_metrics_are_collected_values_or_unknown_never_placeholders() {
+    for age in [None, Some(0), Some(181), Some(-120)] {
+        let tmp = tempfile::tempdir().unwrap();
+        let mut config = crate::config::Config::default();
+        config.data_dir = tmp.path().to_path_buf();
+        let metrics = Arc::new(crate::monitoring::MetricsStore::new());
+        if let Some(age) = age {
+            metrics
+                .push(
+                    serde_json::from_value(serde_json::json!({
+                        "timestamp": chrono::Utc::now().timestamp() - age,
+                        "system": {"cpu_percent": 37.5, "mem_used_bytes": 200,
+                            "mem_total_bytes": 800, "disk_used_bytes": 600,
+                            "disk_total_bytes": 1000, "net_rx_bytes": 0, "net_tx_bytes": 0,
+                            "load_avg_1": 0.0, "load_avg_5": 0.0, "load_avg_15": 0.0},
+                        "containers": [], "rpc_latency_ms": 0.0, "ws_connections": 0
+                    }))
+                    .unwrap(),
+                )
+                .await;
+        }
+        let handler = crate::api::rpc::RpcHandler::new(
+            config,
+            Arc::new(crate::state::StateManager::new()),
+            metrics,
+            crate::session::SessionStore::new_for_tests(tmp.path().join("sessions.json")),
+            None,
+            None,
+        )
+        .await
+        .unwrap();
+        let snapshot = handler.handle_federation_get_state().await.unwrap();
+        if age == Some(0) {
+            assert_eq!(snapshot["cpu_usage_percent"], 37.5);
+            assert_eq!(snapshot["mem_used_bytes"], 200);
+            assert_eq!(snapshot["disk_total_bytes"], 1000);
+        } else {
+            for field in [
+                "cpu_usage_percent",
+                "mem_used_bytes",
+                "mem_total_bytes",
+                "disk_used_bytes",
+                "disk_total_bytes",
+            ] {
+                assert!(
+                    snapshot.get(field).is_none_or(|v| v.is_null()),
+                    "{age:?}: {field}"
+                );
+            }
+        }
+        let peer = serde_json::from_value(serde_json::json!({
+            "did": "did:key:test", "pubkey": "11".repeat(32), "onion": "test.onion",
+            "trust_level": "trusted", "added_at": chrono::Utc::now().to_rfc3339(),
+            "last_state": snapshot
+        }))
+        .unwrap();
+        crate::federation::save_nodes(tmp.path(), &[peer])
+            .await
+            .unwrap();
+        let fleet = handler.handle_telemetry_fleet_status().await.unwrap();
+        let report = &fleet["nodes"][0];
+        if age == Some(0) {
+            assert_eq!(report["cpu_pct"], 38.0);
+            assert_eq!(report["mem_pct"], 25.0);
+            assert_eq!(report["disk_pct"], 60.0);
+        } else {
+            for field in ["cpu_pct", "mem_pct", "disk_pct"] {
+                assert!(report[field].is_null(), "{age:?}: {field}");
+            }
+        }
+    }
+}
+
+/// Real encrypted relay -> poll -> persisted membership, including the normal
+/// npub-only outbound request whose DID is unknown until the authenticated reply.
+#[tokio::test]
+async fn npub_only_request_accepts_bound_reply_but_rejects_other_sender_and_forged_did() {
+    use base64::Engine;
+    use nostr_sdk::{EventBuilder, Kind, Tag};
+    let dir = tempfile::tempdir().unwrap();
+    let local = Keys::parse(&"11".repeat(32)).unwrap();
+    let remote = Keys::parse(&"22".repeat(32)).unwrap();
+    let stranger = Keys::parse(&"55".repeat(32)).unwrap();
+    let remote_key = "44".repeat(32);
+    let remote_did = crate::identity::did_key_from_pubkey_hex(&remote_key).unwrap();
+    let payload = serde_json::json!({"did":remote_did,"pubkey":remote_key,"onion":format!("{}.onion","b".repeat(56)),"token":"fixture-invite"});
+    let event = |sender: &Keys, payload: &serde_json::Value| {
+        let code = format!(
+            "fed1:{}",
+            base64::engine::general_purpose::URL_SAFE_NO_PAD
+                .encode(serde_json::to_vec(payload).unwrap())
+        );
+        let content = nip44::encrypt(
+            sender.secret_key(),
+            &local.public_key(),
+            serde_json::json!({"type":"peer-invite","invite_code":code}).to_string(),
+            nip44::Version::V2,
+        )
+        .unwrap();
+        EventBuilder::new(Kind::EncryptedDirectMessage, content)
+            .tag(Tag::public_key(local.public_key()))
+            .sign_with_keys(sender)
+            .unwrap()
+    };
+    let mut forged = payload.clone();
+    forged["pubkey"] = serde_json::json!("66".repeat(32));
+    let events = Arc::new(std::sync::Mutex::new(vec![
+        event(&stranger, &payload),
+        event(&remote, &forged),
+    ]));
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let relay_url = format!("ws://{}", listener.local_addr().unwrap());
+    let relay_events = events.clone();
+    let relay = tokio::spawn(async move {
+        while let Ok((socket, _)) = listener.accept().await {
+            let events = relay_events.clone();
+            tokio::spawn(async move {
+                let Ok(mut ws) = tokio_tungstenite::accept_async(socket).await else {
+                    return;
+                };
+                while let Some(Ok(message)) = ws.next().await {
+                    let Ok(text) = message.to_text() else {
+                        continue;
+                    };
+                    let Ok(value) = serde_json::from_str::<serde_json::Value>(text) else {
+                        continue;
+                    };
+                    if value[0] != "REQ" {
+                        continue;
+                    }
+                    let stored = events.lock().unwrap().clone();
+                    for event in stored {
+                        if ws
+                            .send(tokio_tungstenite::tungstenite::Message::Text(
+                                serde_json::json!(["EVENT", value[1], event]).to_string(),
+                            ))
+                            .await
+                            .is_err()
+                        {
+                            return;
+                        }
+                    }
+                    if ws
+                        .send(tokio_tungstenite::tungstenite::Message::Text(
+                            serde_json::json!(["EOSE", value[1]]).to_string(),
+                        ))
+                        .await
+                        .is_err()
+                    {
+                        return;
+                    }
+                }
+            });
+        }
+    });
+    let identity_dir = dir.path().join("identity");
+    tokio::fs::create_dir_all(&identity_dir).await.unwrap();
+    tokio::fs::write(identity_dir.join("nostr_secret"), "11".repeat(32))
+        .await
+        .unwrap();
+    let identity = crate::identity::NodeIdentity::load_or_create(&identity_dir)
+        .await
+        .unwrap();
+    tokio::fs::write(
+        dir.path()
+            .join(crate::nostr_handshake::DISCOVERY_STATE_FILE),
+        br#"{"enabled":true}"#,
+    )
+    .await
+    .unwrap();
+    let mut config = crate::config::Config::default();
+    config.data_dir = dir.path().into();
+    config.nostr_relays = vec![relay_url];
+    config.nostr_tor_proxy = None;
+    let state = Arc::new(crate::state::StateManager::new());
+    state
+        .mutate_data(|data| {
+            data.server_info.pubkey = identity.pubkey_hex();
+            data.server_info.tor_address = Some(format!("{}.onion", "a".repeat(56)));
+        })
+        .await;
+    let handler = crate::api::rpc::RpcHandler::new(
+        config,
+        state,
+        Arc::new(crate::monitoring::MetricsStore::new()),
+        crate::session::SessionStore::new_for_tests(dir.path().join("sessions.json")),
+        None,
+        None,
+    )
+    .await
+    .unwrap();
+    let row = pending::insert_outbound(
+        dir.path(),
+        remote.public_key().to_hex(),
+        String::new(),
+        String::new(),
+        None,
+        None,
+    )
+    .await
+    .unwrap();
+    let rejected = handler.handle_handshake_poll().await.unwrap();
+    assert!(rejected["applied_invites"].as_array().unwrap().is_empty());
+    assert!(crate::federation::load_nodes(dir.path())
+        .await
+        .unwrap()
+        .is_empty());
+    assert_eq!(
+        pending::find_by_id(dir.path(), &row.id)
+            .await
+            .unwrap()
+            .unwrap()
+            .state,
+        PendingState::Sent
+    );
+    *events.lock().unwrap() = vec![event(&remote, &payload)];
+    let accepted = handler.handle_handshake_poll().await.unwrap();
+    assert_eq!(accepted["applied_invites"], serde_json::json!([remote_did]));
+    let nodes = crate::federation::load_nodes(dir.path()).await.unwrap();
+    assert_eq!(nodes.len(), 1);
+    assert_eq!(
+        nodes[0].trust_level,
+        crate::federation::TrustLevel::Observer
+    );
+    assert_eq!(
+        pending::find_by_id(dir.path(), &row.id)
+            .await
+            .unwrap()
+            .unwrap()
+            .state,
+        PendingState::Approved
+    );
+    assert_eq!(
+        pending::find_by_id(dir.path(), &row.id)
+            .await
+            .unwrap()
+            .unwrap()
+            .from_did,
+        remote_did
+    );
+    let duplicate = handler.handle_handshake_poll().await.unwrap();
+    assert!(duplicate["applied_invites"].as_array().unwrap().is_empty());
+    assert_eq!(
+        crate::federation::load_nodes(dir.path())
+            .await
+            .unwrap()
+            .len(),
+        1
+    );
+    relay.abort();
+}

core/archipelago/src/api/rpc/federation/mod.rs

@@ -1,4 +1,6 @@
 mod handlers;
+#[cfg(test)]
+mod handshake_tests;
 
 use anyhow::Result;
 

core/archipelago/src/api/rpc/handshake.rs

@@ -276,6 +276,11 @@ impl RpcHandler {
             }
             Err(e) => tracing::debug!("background handshake poll failed: {e:#}"),
         }
+        if load_discovery_state(&self.config.data_dir).await.enabled {
+            if let Err(error) = self.retry_peer_approval_replies().await {
+                tracing::warn!("Peer approval retry could not complete: {error:#}");
+            }
+        }
     }
 
     pub(super) async fn handle_handshake_poll(&self) -> Result<serde_json::Value> {
@@ -340,6 +345,7 @@ impl RpcHandler {
                     }
                 }
                 HandshakeMessage::PeerInvite { invite_code } => {
+                    let _decision = pending::outbound_decision_guard().await;
                     // Match against an outbound Sent request from this nostr
                     // pubkey. If we never sent them anything, ignore — we
                     // don't accept unsolicited invites over Nostr.
@@ -356,6 +362,16 @@ impl RpcHandler {
                         );
                         continue;
                     };
+                    let scoped_invite = match crate::federation::restrict_discovery_invite(
+                        invite_code,
+                        &row.from_did,
+                    ) {
+                        Ok(code) => code,
+                        Err(_) => {
+                            tracing::warn!("Rejected peer invite with mismatched identity");
+                            continue;
+                        }
+                    };
                     let row_id = row.id.clone();
                     let (data, _) = self.state_manager.get_snapshot().await;
                     let local_did =
@@ -373,7 +389,7 @@ impl RpcHandler {
                     let local_name = data.server_info.name.clone();
                     match crate::federation::accept_invite(
                         &self.config.data_dir,
-                        invite_code,
+                        &scoped_invite,
                         &local_did,
                         &local_onion,
                         &local_pubkey,
@@ -416,10 +432,11 @@ impl RpcHandler {
                                 .await;
                             }
 
-                            pending::set_state(
+                            pending::complete_outbound(
                                 &self.config.data_dir,
                                 &row_id,
-                                PendingState::Approved,
+                                &hs.from_nostr_pubkey,
+                                &node.did,
                             )
                             .await?;
                             applied_invites.push(node.did);
@@ -434,6 +451,7 @@ impl RpcHandler {
                     }
                 }
                 HandshakeMessage::PeerReject { reason } => {
+                    let _decision = pending::outbound_decision_guard().await;
                     let pendings = pending::load_pending(&self.config.data_dir).await?;
                     if let Some(row) = pendings.iter().find(|r| {
                         r.outbound

core/archipelago/src/api/rpc/identity/handlers.rs

@@ -1,6 +1,8 @@
 use super::*;
 use crate::api::rpc::RpcHandler;
-use crate::identity_manager::{IdentityManager, IdentityProfile, IdentityPurpose};
+use crate::identity_manager::{
+    is_node_identity, IdentityManager, IdentityProfile, IdentityPurpose,
+};
 use crate::network::did_dht;
 use anyhow::{Context, Result};
 use nostr_sdk::ToBech32;
@@ -38,7 +40,7 @@ impl RpcHandler {
             .into_iter()
             .map(|id| {
                 let is_default = default_id.as_deref() == Some(&id.id);
-                let is_node = !node_pubkey_hex.is_empty() && id.pubkey_hex == node_pubkey_hex;
+                let is_node = is_node_identity(&id, &node_pubkey_hex);
                 let (nostr_pubkey, nostr_npub) = if is_node {
                     (
                         node_nostr_hex.clone().or(id.nostr_pubkey),

core/archipelago/src/api/rpc/lightning_purchase.rs

@@ -0,0 +1,358 @@
+use super::RpcHandler;
+use crate::{
+    api::handler::lightning_purchase::{Operation, ROUTE},
+    content_lightning::{Binding, BuyerRecord, Journal, Phase, Status},
+};
+use anyhow::{Context, Result};
+use serde::Deserialize;
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Params {
+    onion: String,
+    content_id: String,
+    price_sats: Option<u64>,
+    operation_id: Option<String>,
+    #[serde(default)]
+    external_exposure: bool,
+}
+impl RpcHandler {
+    pub(super) async fn handle_lightning_operation(
+        &self,
+        params: Option<serde_json::Value>,
+        action: &str,
+    ) -> Result<serde_json::Value> {
+        let params: Params = serde_json::from_value(params.context("Missing invoice operation")?)?;
+        let peer =
+            crate::federation::load_unique_payment_peer(&self.config.data_dir, &params.onion)
+                .await?;
+        let fips = peer
+            .fips_npub
+            .context("Seller has no authenticated mesh connection")?;
+        let buyer =
+            crate::identity::NodeIdentity::load_existing(&self.config.data_dir.join("identity"))
+                .await?
+                .did_key()?;
+        anyhow::ensure!(buyer != peer.did, "Cannot buy a file from this same node");
+        let _admission = crate::content_payment_admission::lock(
+            &self.config.data_dir,
+            &buyer,
+            &peer.did,
+            &params.content_id,
+        )
+        .await?;
+        if matches!(action, "create" | "pay" | "retry") || params.external_exposure {
+            self.ensure_onchain_allows_other_rail(&buyer, &peer.did, &params.content_id)
+                .await?;
+            let cashu = crate::content_purchase::Journal::open(&self.config.data_dir).await?;
+            anyhow::ensure!(
+                cashu
+                    .find_buyers(&buyer, &peer.did, &params.content_id)
+                    .await?
+                    .iter()
+                    .all(|r| r.phase == crate::content_purchase::BuyerPhase::Cancelled),
+                "Recover or cancel the original Cashu purchase before exposing a Lightning invoice"
+            );
+        }
+        let journal = Journal::open(&self.config.data_dir).await?;
+        let original = if let Some(id) = &params.operation_id {
+            journal.buyer(id)?
+        } else {
+            journal.buyer_for(&buyer, &peer.did, &params.content_id)?
+        };
+        if let Some(record) = &original {
+            anyhow::ensure!(
+                record.binding.buyer_did == buyer
+                    && record.binding.seller_did == peer.did
+                    && record.binding.content_id == params.content_id
+                    && record.seller_onion == params.onion,
+                "Original invoice belongs to another purchase"
+            );
+        }
+        if action == "lookup" {
+            return Ok(match original {
+                None => serde_json::json!({"attempt":null}),
+                Some(mut record) => {
+                    let mut native_result = record.native_result.clone();
+                    if native_result.is_none() && record.native_dispatched {
+                        if let Some(status) = &record.last {
+                            if let Ok(payment) = self
+                                .handle_lnd_paymentstatus(Some(
+                                    serde_json::json!({"payment_hash":status.payment_hash}),
+                                ))
+                                .await
+                            {
+                                if let Some(result @ ("failed" | "succeeded")) =
+                                    payment["status"].as_str()
+                                {
+                                    native_result = Some(result.to_owned());
+                                    record.native_result = native_result.clone();
+                                    journal.save_buyer(&record)?;
+                                }
+                            }
+                        }
+                    }
+                    let native_failed =
+                        !record.external_exposure && native_result.as_deref() == Some("failed");
+                    let native_succeeded = native_result.as_deref() == Some("succeeded");
+                    if !record.external_exposure {
+                        if let Some(status) = record.last.as_mut() {
+                            status.bolt11 = None;
+                        }
+                    }
+                    serde_json::json!({"attempt":{"operation_id":record.binding.id,"price_sats":record.binding.price_sats,"external_exposure":record.external_exposure,"native_failed":native_failed,"native_succeeded":native_succeeded,"status":record.last}})
+                }
+            });
+        }
+        let mut record = if let Some(record) = original {
+            record
+        } else {
+            anyhow::ensure!(
+                action == "create" && params.operation_id.is_none(),
+                "Original invoice operation is unavailable"
+            );
+            BuyerRecord {
+                binding: Binding {
+                    id: uuid::Uuid::new_v4().to_string(),
+                    buyer_did: buyer.clone(),
+                    seller_did: peer.did.clone(),
+                    content_id: params.content_id.clone(),
+                    price_sats: params
+                        .price_sats
+                        .context("Expected invoice price is required")?,
+                },
+                seller_onion: params.onion.clone(),
+                external_exposure: false,
+                native_retired: false,
+                native_replacement: None,
+                native_dispatched: false,
+                native_result: None,
+                last: None,
+            }
+        };
+        anyhow::ensure!(
+            record.binding.buyer_did == buyer
+                && record.binding.seller_did == peer.did
+                && record.binding.content_id == params.content_id
+                && record.seller_onion == params.onion
+                && params
+                    .operation_id
+                    .as_ref()
+                    .is_none_or(|id| id == &record.binding.id),
+            "Original invoice operation changed"
+        );
+        if action == "retry" {
+            anyhow::ensure!(
+                params.operation_id.is_some()
+                    && !params.external_exposure
+                    && params.price_sats == Some(record.binding.price_sats),
+                "Explicit original native retry and original price required"
+            );
+            if record.native_result.is_none()
+                && record.native_dispatched
+                && !record.external_exposure
+            {
+                let hash = &record
+                    .last
+                    .as_ref()
+                    .context("Original invoice metadata missing")?
+                    .payment_hash;
+                let payment = self
+                    .handle_lnd_paymentstatus(Some(serde_json::json!({"payment_hash":hash})))
+                    .await?;
+                if matches!(payment["status"].as_str(), Some("failed" | "succeeded")) {
+                    record.native_result = payment["status"].as_str().map(str::to_owned);
+                    journal.save_buyer(&record)?;
+                }
+            }
+            record = journal.retry_native(&record.binding.id)?;
+        }
+        anyhow::ensure!((!record.native_retired || matches!(action,"status"|"cancel"|"download")) && (!record.native_retired || !params.external_exposure),"This native invoice was retired before changing payment method; recover the replacement purchase");
+        if action == "pay" {
+            anyhow::ensure!(
+                params.operation_id.is_some(),
+                "Original invoice operation required for native payment"
+            );
+            return crate::content_lightning::drive_native(
+                &self.config.data_dir,
+                journal,
+                &record.binding.id,
+                &super::lnd::external_invoice::NativeNode(self),
+            )
+            .await;
+        }
+        record.external_exposure |= params.external_exposure;
+        journal.save_buyer(&record)?;
+        drop(journal);
+        // Native-only local FAILED never cancels an externally exposed invoice.
+        // The seller terminal state is authoritative regardless of UI receipt loss.
+        let operation = Operation {
+            binding: record.binding.clone(),
+            action: if action == "retry" {
+                "create".into()
+            } else {
+                action.into()
+            },
+        };
+        let response = crate::fips::dial::PeerRequest::new(Some(&fips), &params.onion, ROUTE)
+            .require_fips()
+            .single_delivery()
+            .timeout(std::time::Duration::from_secs(if action == "download" {
+                900
+            } else {
+                45
+            }))
+            .send_content_json(&self.config.data_dir, &peer.did, &operation)
+            .await;
+        let mut response = match response {
+            Ok((r, _)) => r,
+            Err(_) => {
+                return Ok(
+                    serde_json::json!({"state":"unknown","operation_id":record.binding.id,"recovery_required":true,"error":"The original invoice request is saved on this node. Recover it; no replacement invoice was requested."}),
+                )
+            }
+        };
+        anyhow::ensure!(
+            response.status().is_success(),
+            "Seller could not resolve original invoice; recover operation {}",
+            record.binding.id
+        );
+        let journal = Journal::open(&self.config.data_dir).await?;
+        if action == "download" {
+            let mut paid = record
+                .last
+                .clone()
+                .context("Original invoice metadata missing; recover it first")?;
+            let source = paid
+                .source
+                .clone()
+                .context("Original invoice snapshot missing")?;
+            anyhow::ensure!(
+                response.content_length() == Some(source.size),
+                "Original invoice file length changed"
+            );
+            paid.state = Phase::Settled;
+            paid.can_switch_method = false;
+            record.last = Some(paid);
+            journal.save_buyer(&record)?;
+            drop(journal);
+            let stream = crate::content_purchase_download::verified_stream(
+                response.bytes_stream(),
+                source.sha256,
+                source.size,
+            );
+            let owned = crate::content_owned::record_purchase_stream(
+                &self.config.data_dir,
+                crate::content_owned::OwnedItem {
+                    onion: params.onion,
+                    content_id: params.content_id,
+                    filename: source.filename,
+                    mime_type: source.mime_type,
+                    size_bytes: source.size,
+                    paid_sats: record.binding.price_sats,
+                    ecash_backend: "lightning".into(),
+                    purchased_at: chrono::Utc::now().to_rfc3339(),
+                    download_complete: false,
+                },
+                Box::pin(stream),
+                Some(source.size),
+            )
+            .await?;
+            return Ok(
+                serde_json::json!({"owned":true,"owned_content_id":owned.content_id,"mime_type":owned.mime_type}),
+            );
+        }
+        let mut bytes = Vec::new();
+        while let Some(chunk) = response.chunk().await? {
+            anyhow::ensure!(
+                bytes.len() + chunk.len() <= 16384,
+                "Invoice response too large"
+            );
+            bytes.extend_from_slice(&chunk)
+        }
+        let status: Status = serde_json::from_slice(&bytes)?;
+        anyhow::ensure!(
+            status.binding == record.binding
+                && status.source.is_some()
+                && status.payment_hash.len() == 64
+                && status.payment_hash.bytes().all(|b| b.is_ascii_hexdigit())
+                && status.can_switch_method == (status.state == Phase::CanceledUnpaid),
+            "Seller invoice binding changed"
+        );
+        if let Some(bolt11) = &status.bolt11 {
+            let invoice: lightning_invoice::Bolt11Invoice =
+                bolt11.parse().context("Seller invoice is invalid")?;
+            invoice.check_signature()?;
+            anyhow::ensure!(
+                invoice.payment_hash().to_string() == status.payment_hash
+                    && invoice.amount_milli_satoshis()
+                        == record.binding.price_sats.checked_mul(1000),
+                "Invoice hash or amount differs from saved purchase"
+            );
+        }
+        if let Some(previous) = &record.last {
+            anyhow::ensure!(
+                previous.payment_hash == status.payment_hash
+                    && previous.source == status.source
+                    && previous
+                        .bolt11
+                        .as_ref()
+                        .is_none_or(|v| status.bolt11.as_ref() == Some(v)),
+                "Original invoice replaced"
+            );
+        }
+        record.last = Some(status.clone());
+        journal.save_buyer(&record)?;
+        Ok(
+            serde_json::json!({"operation_id":record.binding.id,"price_sats":record.binding.price_sats,"payment_hash":status.payment_hash,"bolt11":if record.external_exposure{status.bolt11}else{None},"state":match status.state{Phase::Settled=>"settled",Phase::CanceledUnpaid=>"canceled",Phase::Issued=>"open",Phase::Prepared=>"prepared",Phase::Dispatched=>"unknown",Phase::CancelRequested=>"cancel_requested"},"paid":status.state==Phase::Settled,"can_switch_method":status.can_switch_method,"cancel_supported":true,"external_exposure":record.external_exposure}),
+        )
+    }
+}
+
+impl RpcHandler {
+    /// Caller holds content_payment_admission before entering any rail journal.
+    pub(super) async fn ensure_invoice_allows_other_rail(
+        &self,
+        buyer: &str,
+        seller: &str,
+        content: &str,
+    ) -> Result<()> {
+        let journal = Journal::open(&self.config.data_dir).await?;
+        if let Some(mut record) = journal.buyer_for(buyer, seller, content)? {
+            anyhow::ensure!(record.native_replacement.is_none(),
+                "An explicit native retry is being recovered; recover its replacement operation first");
+            anyhow::ensure!(
+                !record.external_exposure,
+                "An externally payable invoice remains unresolved; cancel or recover it first"
+            );
+            let status = record
+                .last
+                .clone()
+                .context("Original invoice creation is unresolved; recover it first")?;
+            anyhow::ensure!(
+                status.state != Phase::Settled,
+                "Original Lightning purchase is paid; recover its file"
+            );
+            // A local terminal failure can release only a never-exposed native
+            // attempt. This check runs under the same outer lock as QR exposure.
+            anyhow::ensure!(
+                record.native_dispatched,
+                "Original invoice has not been canceled; cancel it before replacing the method"
+            );
+            if record.native_result.as_deref() != Some("failed") {
+                let payment = self
+                    .handle_lnd_paymentstatus(Some(
+                        serde_json::json!({"payment_hash":status.payment_hash}),
+                    ))
+                    .await?;
+                anyhow::ensure!(
+                    payment["status"] == "failed",
+                    "Original native Lightning attempt remains unresolved"
+                );
+            }
+            record.native_result = Some("failed".into());
+            record.native_retired = true;
+            journal.save_buyer(&record)?;
+        }
+        Ok(())
+    }
+}

core/archipelago/src/api/rpc/lnd/channels.rs

@@ -272,28 +272,8 @@ impl RpcHandler {
             .and_then(|v| v.as_bool())
             .unwrap_or(false);
 
-        // Fee control: either a confirmation target or an explicit fee rate
-        let target_conf = params.get("target_conf").and_then(|v| v.as_i64());
-        let sat_per_vbyte = params.get("sat_per_vbyte").and_then(|v| v.as_i64());
-        if target_conf.is_some() && sat_per_vbyte.is_some() {
-            return Err(anyhow::anyhow!(
-                "Invalid fee parameters: specify either target_conf or sat_per_vbyte, not both"
-            ));
-        }
-        if let Some(tc) = target_conf {
-            if !(1..=1008).contains(&tc) {
-                return Err(anyhow::anyhow!(
-                    "Invalid target_conf: must be between 1 and 1008 blocks"
-                ));
-            }
-        }
-        if let Some(rate) = sat_per_vbyte {
-            if !(1..=5000).contains(&rate) {
-                return Err(anyhow::anyhow!(
-                    "Invalid sat_per_vbyte: must be between 1 and 5000"
-                ));
-            }
-        }
+        // Omitted fees target the next block; explicit slower/custom choices win.
+        let (target_conf, sat_per_vbyte) = super::fee_policy::fee_options(&params)?;
 
         info!(
             peer = pubkey,
@@ -473,6 +453,7 @@ impl RpcHandler {
             ));
         }
 
+        let fee_query = close_channel_fee_query(&params)?;
         let force = params
             .get("force")
             .and_then(|v| v.as_bool())
@@ -498,13 +479,11 @@ impl RpcHandler {
             .build()
             .context("Failed to create streaming HTTP client")?;
 
-        let url = format!(
-            "{LND_REST_BASE_URL}/v1/channels/{}/{}?force={}",
-            parts[0], parts[1], force
-        );
+        let url = format!("{LND_REST_BASE_URL}/v1/channels/{}/{}", parts[0], parts[1]);
 
         let mut resp = client
             .delete(&url)
+            .query(&fee_query)
             .header("Grpc-Metadata-macaroon", &macaroon_hex)
             .send()
             .await
@@ -572,3 +551,106 @@ impl RpcHandler {
         }
     }
 }
+
+/// LND's CloseChannel REST endpoint takes fee selection as query parameters.
+/// With neither parameter LND uses a lax target; keep legacy clients on our
+/// explicit next-block target rather than silently accepting that default.
+fn close_channel_fee_query(params: &serde_json::Value) -> Result<Vec<(&'static str, String)>> {
+    let force = match params.get("force") {
+        None | Some(serde_json::Value::Null) => false,
+        Some(value) => value
+            .as_bool()
+            .ok_or_else(|| anyhow::anyhow!("force must be a boolean"))?,
+    };
+    let integer = |key: &str, max: u64| -> Result<Option<u64>> {
+        match params.get(key) {
+            None | Some(serde_json::Value::Null) => Ok(None),
+            Some(value) => {
+                let n = value
+                    .as_u64()
+                    .ok_or_else(|| anyhow::anyhow!("{key} must be a positive whole number"))?;
+                anyhow::ensure!((1..=max).contains(&n), "{key} must be between 1 and {max}");
+                Ok(Some(n))
+            }
+        }
+    };
+    let target = integer("target_conf", 1008)?;
+    let rate = integer("sat_per_vbyte", 5000)?;
+    anyhow::ensure!(
+        target.is_none() || rate.is_none(),
+        "Specify either target_conf or sat_per_vbyte, not both"
+    );
+    anyhow::ensure!(
+        !force || (target.is_none() && rate.is_none()),
+        "Closing fee selection requires a cooperative close"
+    );
+    let mut query = vec![("force", force.to_string())];
+    if !force {
+        if let Some(rate) = rate {
+            query.push(("sat_per_vbyte", rate.to_string()));
+        } else {
+            query.push((
+                "target_conf",
+                target
+                    .unwrap_or(super::fee_policy::DEFAULT_TARGET as u64)
+                    .to_string(),
+            ));
+        }
+    }
+    Ok(query)
+}
+
+#[cfg(test)]
+mod close_fee_tests {
+    use super::*;
+    #[test]
+    fn close_fee_query_forwards_presets_custom_and_legacy_default() {
+        for target in [1, 3, 6, 1008] {
+            assert_eq!(
+                close_channel_fee_query(&serde_json::json!({"target_conf":target})).unwrap(),
+                vec![
+                    ("force", "false".into()),
+                    ("target_conf", target.to_string())
+                ]
+            );
+        }
+        for rate in [1, 25, 5000] {
+            let query =
+                close_channel_fee_query(&serde_json::json!({"sat_per_vbyte":rate})).unwrap();
+            let request = reqwest::Client::new()
+                .delete("http://localhost/v1/channels/test/0")
+                .query(&query)
+                .build()
+                .unwrap();
+            assert_eq!(request.method(), reqwest::Method::DELETE);
+            assert_eq!(
+                request.url().query(),
+                Some(format!("force=false&sat_per_vbyte={rate}").as_str())
+            );
+        }
+        assert_eq!(
+            close_channel_fee_query(&serde_json::json!({})).unwrap(),
+            vec![("force", "false".into()), ("target_conf", "1".into())]
+        );
+        assert_eq!(
+            close_channel_fee_query(&serde_json::json!({"force":true})).unwrap(),
+            vec![("force", "true".into())]
+        );
+    }
+    #[test]
+    fn malformed_or_conflicting_close_fees_fail_before_wallet_access() {
+        for params in [
+            serde_json::json!({"target_conf":1,"sat_per_vbyte":2}),
+            serde_json::json!({"force":true,"target_conf":1}),
+            serde_json::json!({"force":"false"}),
+            serde_json::json!({"target_conf":0}),
+            serde_json::json!({"target_conf":1009}),
+            serde_json::json!({"sat_per_vbyte":5001}),
+            serde_json::json!({"sat_per_vbyte":-1}),
+            serde_json::json!({"sat_per_vbyte":1.5}),
+            serde_json::json!({"sat_per_vbyte":"25"}),
+        ] {
+            assert!(close_channel_fee_query(&params).is_err(), "{params}");
+        }
+    }
+}

core/archipelago/src/api/rpc/lnd/external_invoice.rs

@@ -0,0 +1,201 @@
+use super::LND_REST_BASE_URL;
+use crate::{
+    api::rpc::RpcHandler,
+    content_lightning::{Binding, Invoice, InvoiceNode, Journal, Status},
+};
+use anyhow::{Context, Result};
+use base64::Engine;
+struct Node {
+    client: reqwest::Client,
+    macaroon: String,
+}
+fn number(v: &serde_json::Value) -> Option<u64> {
+    v.as_u64().or_else(|| v.as_str()?.parse().ok())
+}
+impl InvoiceNode for Node {
+    async fn prepare_creation(&self) -> Result<()> {
+        let info: serde_json::Value = self
+            .client
+            .get(format!("{LND_REST_BASE_URL}/v1/getinfo"))
+            .header("Grpc-Metadata-macaroon", &self.macaroon)
+            .send()
+            .await?
+            .error_for_status()?
+            .json()
+            .await?;
+        anyhow::ensure!(
+            info["identity_pubkey"]
+                .as_str()
+                .is_some_and(|key| !key.is_empty()),
+            "LND invoice service is not ready; original preparation retained"
+        );
+        Ok(())
+    }
+    async fn lookup(&self, hash: &str) -> Result<Option<Invoice>> {
+        let response = self
+            .client
+            .get(format!("{LND_REST_BASE_URL}/v1/invoice/{hash}"))
+            .header("Grpc-Metadata-macaroon", &self.macaroon)
+            .send()
+            .await?;
+        if response.status() == reqwest::StatusCode::NOT_FOUND {
+            return Ok(None);
+        }
+        let body: serde_json::Value = response.error_for_status()?.json().await?;
+        let raw = body["r_hash"].as_str().context("Invoice hash omitted")?;
+        let payment_hash = hex::encode(base64::engine::general_purpose::STANDARD.decode(raw)?);
+        Ok(Some(Invoice {
+            payment_hash,
+            bolt11: body["payment_request"]
+                .as_str()
+                .context("Invoice payment request omitted")?
+                .into(),
+            price_sats: number(&body["value"]).context("Invoice amount omitted")?,
+            state: body["state"]
+                .as_str()
+                .context("Invoice state omitted")?
+                .into(),
+            paid_sats: number(&body["amt_paid_sat"]),
+            paid_msats: number(&body["amt_paid_msat"]),
+        }))
+    }
+    async fn add(&self, binding: &Binding, preimage_hex: &str) -> Result<()> {
+        let preimage = base64::engine::general_purpose::STANDARD.encode(hex::decode(preimage_hex)?);
+        self.client.post(format!("{LND_REST_BASE_URL}/v1/invoices")).header("Grpc-Metadata-macaroon",&self.macaroon)
+            .json(&serde_json::json!({"memo":format!("Archipelago peer file {}",binding.content_id),"value":binding.price_sats.to_string(),"r_preimage":preimage,"private":true,"expiry":"3600"})).send().await?.error_for_status()?;
+        Ok(())
+    }
+    async fn cancel(&self, hash: &str) -> Result<()> {
+        self.client.post(format!("{LND_REST_BASE_URL}/v2/invoices/cancel")).header("Grpc-Metadata-macaroon",&self.macaroon)
+            .json(&serde_json::json!({"payment_hash":base64::engine::general_purpose::STANDARD.encode(hex::decode(hash)?)})).send().await?.error_for_status()?;
+        Ok(())
+    }
+}
+impl RpcHandler {
+    pub(crate) async fn drive_external_invoice(
+        &self,
+        journal: &Journal,
+        binding: &Binding,
+        cancel: bool,
+    ) -> Result<Status> {
+        // Configuration/auth preflight before the engine persists dispatch.
+        let (client, macaroon) = self.lnd_client().await?;
+        crate::content_lightning::drive(journal, binding, &Node { client, macaroon }, cancel).await
+    }
+}
+
+/// Prepared before the durable native-dispatch marker. Once execute is called,
+/// every transport error is ambiguous and only original-hash lookup may follow.
+pub(crate) struct PreparedNativePayment {
+    client: reqwest::Client,
+    request: reqwest::Request,
+    hash: String,
+    amount: u64,
+}
+impl PreparedNativePayment {
+    pub(crate) async fn execute(self) -> Result<serde_json::Value> {
+        let response = self
+            .client
+            .execute(self.request)
+            .await
+            .context("Native payment response is unknown; recover the original operation")?;
+        let status = response.status();
+        let body: serde_json::Value = response
+            .json()
+            .await
+            .context("Native payment response is unknown")?;
+        anyhow::ensure!(
+            status.is_success(),
+            "LND did not confirm the original payment; recover its status"
+        );
+        let payment = body.get("result").unwrap_or(&body);
+        anyhow::ensure!(
+            payment
+                .get("payment_hash")
+                .and_then(|v| v.as_str())
+                .is_none_or(|hash| hash == self.hash),
+            "LND payment hash changed"
+        );
+        Ok(super::payments::router_payment_outcome(
+            payment,
+            &self.hash,
+            self.amount as i64,
+        ))
+    }
+}
+impl RpcHandler {
+    pub(crate) async fn prepare_bound_invoice_payment(
+        &self,
+        bolt11: &str,
+        hash: &str,
+        amount: u64,
+    ) -> Result<PreparedNativePayment> {
+        let invoice: lightning_invoice::Bolt11Invoice =
+            bolt11.parse().context("Invalid original invoice")?;
+        invoice.check_signature()?;
+        anyhow::ensure!(
+            invoice.payment_hash().to_string() == hash
+                && invoice.amount_milli_satoshis() == amount.checked_mul(1000),
+            "Original invoice amount/hash changed"
+        );
+        anyhow::ensure!(
+            !invoice.is_expired(),
+            "Original invoice expired; cancel or recover it before choosing another method"
+        );
+        let (client, macaroon) = self.lnd_client().await?;
+        let info: serde_json::Value = client
+            .get(format!("{LND_REST_BASE_URL}/v1/getinfo"))
+            .header("Grpc-Metadata-macaroon", &macaroon)
+            .send()
+            .await?
+            .error_for_status()?
+            .json()
+            .await?;
+        let network = match invoice.currency() {
+            lightning_invoice::Currency::Bitcoin => "mainnet",
+            lightning_invoice::Currency::BitcoinTestnet => "testnet",
+            lightning_invoice::Currency::Regtest => "regtest",
+            lightning_invoice::Currency::Signet => "signet",
+            lightning_invoice::Currency::Simnet => "simnet",
+        };
+        anyhow::ensure!(
+            info["chains"].as_array().is_some_and(|chains| chains
+                .iter()
+                .any(|chain| chain["chain"] == "bitcoin" && chain["network"] == network)),
+            "Original invoice belongs to another Bitcoin network"
+        );
+        let client = reqwest::Client::builder()
+            .no_proxy()
+            .connect_timeout(std::time::Duration::from_secs(10))
+            .timeout(std::time::Duration::from_secs(8))
+            .danger_accept_invalid_certs(true)
+            .build()?;
+        let request=client.post(format!("{LND_REST_BASE_URL}/v2/router/send")).header("Grpc-Metadata-macaroon",macaroon).json(&serde_json::json!({"payment_request":bolt11,"no_inflight_updates":true,"timeout_seconds":120,"fee_limit_sat":amount})).build()?;
+        Ok(PreparedNativePayment {
+            client,
+            request,
+            hash: hash.into(),
+            amount,
+        })
+    }
+}
+
+impl crate::content_lightning::PreparedPayment for PreparedNativePayment {
+    async fn execute(self) -> Result<serde_json::Value> {
+        PreparedNativePayment::execute(self).await
+    }
+}
+pub(crate) struct NativeNode<'a>(pub &'a RpcHandler);
+impl crate::content_lightning::NativeInvoiceNode for NativeNode<'_> {
+    type Prepared = PreparedNativePayment;
+    async fn prepare(&self, invoice: &str, hash: &str, amount: u64) -> Result<Self::Prepared> {
+        self.0
+            .prepare_bound_invoice_payment(invoice, hash, amount)
+            .await
+    }
+    async fn lookup_payment(&self, hash: &str) -> Result<serde_json::Value> {
+        self.0
+            .handle_lnd_paymentstatus(Some(serde_json::json!({"payment_hash":hash})))
+            .await
+    }
+}

core/archipelago/src/api/rpc/lnd/fee_bump.rs

@@ -0,0 +1,921 @@
+//! WalletKit BumpFee is CPFP for new wallet outputs, RBF only for sweeper inputs.
+//! Never feed an ordinary payment input to it and call that a replacement.
+use super::LND_REST_BASE_URL;
+use crate::api::rpc::RpcHandler;
+use anyhow::{bail, ensure, Context, Result};
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+use std::{collections::HashMap, path::Path, sync::LazyLock};
+use tokio::{io::AsyncWriteExt, sync::Mutex};
+
+static QUOTES: LazyLock<Mutex<HashMap<String, Quote>>> = LazyLock::new(Default::default);
+// Serialize check/register/persist across dashboard clients. The create_new receipt
+// additionally survives process restarts and prevents retries of ambiguous results.
+static SUBMIT: Mutex<()> = Mutex::const_new(());
+const QUOTE_SECONDS: u64 = 60;
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+struct Plan {
+    txid: String,
+    method: String,
+    input_txid: String,
+    input_index: u32,
+    parent_txid: String,
+    recipient_sats: u64,
+    rate_sat_vb: u64,
+    current_fee_sats: u64,
+    additional_fee_sats: u64,
+    total_fee_sats: u64,
+    budget_sats: u64,
+    input_sats: u64,
+    parent_vsize: u64,
+    sweep_vsize_bound: u64,
+    tip: String,
+}
+#[derive(Clone, Serialize, Deserialize)]
+struct Quote {
+    quote_id: String,
+    expires_at: u64,
+    custom_rate: Option<u64>,
+    #[serde(flatten)]
+    plan: Plan,
+}
+#[derive(Serialize, Deserialize)]
+struct Operation {
+    quote: Quote,
+    status: String,
+    message: String,
+}
+fn now() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs()
+}
+fn number(v: &Value) -> Result<u64> {
+    v.as_u64()
+        .or_else(|| v.as_str().and_then(|s| s.parse().ok()))
+        .context("Missing or invalid wallet amount")
+}
+fn txid_param(p: &Value) -> Result<String> {
+    let s = p["txid"].as_str().context("Missing transaction ID")?;
+    ensure!(
+        s.len() == 64 && s.bytes().all(|c| c.is_ascii_hexdigit()),
+        "Invalid transaction ID"
+    );
+    Ok(s.to_ascii_lowercase())
+}
+fn btc_sats(v: &Value) -> Result<u64> {
+    let n = v.as_f64().context("Missing Bitcoin fee")? * 100_000_000.0;
+    ensure!(
+        n.is_finite() && n >= 0.0 && n <= 2_100_000_000_000_000.0,
+        "Invalid Bitcoin fee"
+    );
+    Ok(n.round() as u64)
+}
+fn outpoint_matches(v: &Value, txid: &str, index: u32) -> bool {
+    v["txid_str"].as_str() == Some(txid) && v["output_index"].as_u64() == Some(index as u64)
+}
+fn array<'a>(v: &'a Value, key: &str) -> Result<&'a Vec<Value>> {
+    v[key]
+        .as_array()
+        .with_context(|| format!("Missing wallet field: {key}"))
+}
+fn sweep_size(output: &Value) -> Result<u64> {
+    // One native input, one wallet taproot output, including signature rounding.
+    match output["output_type"].as_str() {
+        Some("SCRIPT_TYPE_WITNESS_V1_TAPROOT") => Ok(112),
+        Some("SCRIPT_TYPE_WITNESS_V0_PUBKEY_HASH") => Ok(123),
+        _ => bail!("This output type is not supported for fee bumping yet"),
+    }
+}
+fn fee_budget(
+    rate: u64,
+    parent_size: u64,
+    parent_fee: u64,
+    size: u64,
+    old_fee: u64,
+    relay: u64,
+    input: u64,
+) -> Result<u64> {
+    ensure!(
+        (1..=5000).contains(&rate),
+        "Fee rate must be a whole number from 1 to 5000 sat/vB"
+    );
+    ensure!(
+        parent_size <= 100_000 && size <= 100_000 && relay <= 5000,
+        "Unsupported package size or relay fee"
+    );
+    let required = rate * (parent_size + size);
+    let mut budget = required.saturating_sub(parent_fee).max(relay * size);
+    if old_fee > 0 {
+        budget = budget.max(old_fee + relay * size + 1);
+    }
+    ensure!(budget > old_fee, "Choose a higher fee rate");
+    // Conservative dust buffer; never attach unrelated wallet inputs to fund fees.
+    ensure!(
+        budget.checked_add(1000).is_some_and(|v| v <= input),
+        "Not enough wallet change for this fee; choose a lower rate"
+    );
+    Ok(budget)
+}
+
+/// Find the highest rate that fits the already selected wallet output. This is
+/// only a quote-time calculation: it never asks LND to reserve or spend the
+/// output. Keeping it here lets the caller give an actionable answer when the
+/// requested target is too expensive.
+fn highest_affordable_rate(
+    requested: u64,
+    parent_size: u64,
+    parent_fee: u64,
+    size: u64,
+    old_fee: u64,
+    relay: u64,
+    input: u64,
+) -> Option<u64> {
+    if requested <= 1 {
+        return None;
+    }
+    let mut low = 1;
+    let mut high = requested.saturating_sub(1);
+    let mut best = None;
+    while low <= high {
+        let mid = low + (high - low) / 2;
+        if fee_budget(mid, parent_size, parent_fee, size, old_fee, relay, input).is_ok() {
+            best = Some(mid);
+            low = mid.saturating_add(1);
+        } else {
+            high = mid.saturating_sub(1);
+        }
+    }
+    best
+}
+
+fn quote_budget_error(
+    requested: u64,
+    parent_size: u64,
+    parent_fee: u64,
+    size: u64,
+    old_fee: u64,
+    relay: u64,
+    input: u64,
+) -> anyhow::Error {
+    let available = input.saturating_sub(1000);
+    let suggestion = highest_affordable_rate(
+        requested,
+        parent_size,
+        parent_fee,
+        size,
+        old_fee,
+        relay,
+        input,
+    )
+    .map(|rate| format!(" Try {rate} sat/vB or lower."))
+    .unwrap_or_else(|| " No fee rate can currently fit this output.".into());
+    anyhow::anyhow!(
+        "Not enough wallet change for {requested} sat/vB: at most {available} sats is spendable for this bump.{suggestion}"
+    )
+}
+
+async fn lnd(
+    client: &reqwest::Client,
+    macaroon: &str,
+    path: &str,
+    body: Option<Value>,
+) -> Result<Value> {
+    let url = format!("{LND_REST_BASE_URL}{path}");
+    let req = match body {
+        Some(v) => client.post(url).json(&v),
+        None => client.get(url),
+    };
+    let response = req
+        .header("Grpc-Metadata-macaroon", macaroon)
+        .send()
+        .await?;
+    let status = response.status();
+    let value: Value = response.json().await.context("Invalid LND response")?;
+    ensure!(
+        status.is_success() && value.get("code").is_none(),
+        "{}",
+        value["message"].as_str().unwrap_or("LND request failed")
+    );
+    Ok(value)
+}
+
+fn validate_quote(quote: &Quote, fresh: &Plan, timestamp: u64) -> Result<()> {
+    ensure!(
+        quote.expires_at > timestamp && quote.plan == *fresh,
+        "Transaction or fees changed; review a fresh quote"
+    );
+    Ok(())
+}
+fn bump_body(plan: &Plan) -> Value {
+    json!({"outpoint":{"txid_str":plan.input_txid,"output_index":plan.input_index},
+        "sat_per_vbyte":plan.rate_sat_vb.to_string(), "budget":plan.budget_sats.to_string(),
+        "deadline_delta":1, "immediate":true})
+}
+
+async fn reserve(path: &Path, op: &Operation) -> Result<()> {
+    let parent = path.parent().context("Invalid operation path")?;
+    tokio::fs::create_dir_all(parent).await?;
+    let mut f = tokio::fs::OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .mode(0o600)
+        .open(path)
+        .await
+        .context("A bump already exists for this transaction; check its status")?;
+    f.write_all(&serde_json::to_vec(op)?).await?;
+    f.sync_all().await?;
+    // Sync directory entry too: a crash must not make a submitted operation vanish.
+    tokio::fs::File::open(parent).await?.sync_all().await?;
+    Ok(())
+}
+
+// Only a recorded Archy CPFP with one owned input and no external outputs may
+// be folded into a payment. Labels and a fee-sized delta alone are not evidence.
+fn fee_child_matches(tx: &Value, plan: &Plan) -> bool {
+    let input = format!("{}:{}", plan.input_txid, plan.input_index);
+    let amount = tx["amount"]
+        .as_i64()
+        .or_else(|| tx["amount"].as_str()?.parse().ok());
+    let fee = number(&tx["total_fees"])
+        .ok()
+        .and_then(|n| i64::try_from(n).ok());
+    tx["tx_hash"]
+        .as_str()
+        .is_some_and(|id| id.len() == 64 && id.bytes().all(|c| c.is_ascii_hexdigit()))
+        && amount
+            .zip(fee)
+            .is_some_and(|(amount, fee)| fee > 0 && amount == -fee)
+        && tx["previous_outpoints"].as_array().is_some_and(|inputs| {
+            inputs.len() == 1
+                && inputs[0]["outpoint"] == input
+                && inputs[0]["is_our_output"] == true
+        })
+        && tx["output_details"].as_array().is_some_and(|outputs| {
+            !outputs.is_empty() && outputs.iter().all(|o| o["is_our_address"] == true)
+        })
+}
+
+impl RpcHandler {
+    pub(super) async fn group_fee_bump_history(
+        &self,
+        raw: &[Value],
+        normalized: &mut Vec<Value>,
+        client: &reqwest::Client,
+    ) {
+        let mut hidden = std::collections::HashSet::new();
+        for parent in normalized.iter_mut() {
+            if parent["direction"] != "outgoing" {
+                continue;
+            }
+            let Some(id) = parent["tx_hash"].as_str().map(str::to_owned) else {
+                continue;
+            };
+            if id.len() != 64 || !id.bytes().all(|c| c.is_ascii_hexdigit()) {
+                continue;
+            }
+            let path = self
+                .config
+                .data_dir
+                .join("wallet/fee-bumps")
+                .join(format!("{id}.json"));
+            let Ok(bytes) = tokio::fs::read(path).await else {
+                continue;
+            };
+            let Ok(op) = serde_json::from_slice::<Operation>(&bytes) else {
+                continue;
+            };
+            let plan = &op.quote.plan;
+            if plan.method != "cpfp"
+                || plan.txid != id
+                || plan.parent_txid != id
+                || plan.input_txid != id
+            {
+                continue;
+            }
+            let candidates: Vec<_> = raw
+                .iter()
+                .filter(|tx| fee_child_matches(tx, plan))
+                .collect();
+            let mut active = Vec::new();
+            for child in &candidates {
+                let child_id = child["tx_hash"].as_str().unwrap();
+                if child["num_confirmations"].as_i64().unwrap_or(0) > 0
+                    || self
+                        .bitcoin_rpc_call::<Value>(client, "getmempoolentry", &[json!(child_id)])
+                        .await
+                        .is_ok()
+                {
+                    active.push(*child);
+                }
+            }
+            // Ambiguous or unavailable chain state must not hide wallet history.
+            if active.len() != 1 {
+                continue;
+            }
+            let current = active[0];
+            parent["bump_fee_sats"] = json!(number(&current["total_fees"]).unwrap());
+            parent["fee_bump_txid"] = current["tx_hash"].clone();
+            parent["fee_bump_confirmations"] = current["num_confirmations"].clone();
+            parent["fee_bump_history"] = json!(candidates.iter().map(|child| {
+                let child_id = child["tx_hash"].as_str().unwrap();
+                hidden.insert(child_id.to_owned());
+                json!({"tx_hash":child_id,"fee_sats":number(&child["total_fees"]).unwrap(),
+                    "status":if child["tx_hash"] != current["tx_hash"] { "replaced" }
+                    else if child["num_confirmations"].as_i64().unwrap_or(0) > 0 { "confirmed" } else { "mempool" }})
+            }).collect::<Vec<_>>());
+        }
+        normalized.retain(|tx| !tx["tx_hash"].as_str().is_some_and(|id| hidden.contains(id)));
+    }
+
+    async fn bump_plan(&self, txid: &str, custom_rate: Option<u64>) -> Result<Plan> {
+        let (client, macaroon) = self.lnd_client().await?;
+        let info = lnd(&client, &macaroon, "/v1/getinfo", None).await?;
+        ensure!(
+            info["synced_to_chain"] == true,
+            "Wait for the wallet to finish syncing"
+        );
+        let version = info["version"]
+            .as_str()
+            .context("LND version is unavailable")?;
+        let mut parts = version.trim_start_matches('v').split('.');
+        let major: u32 = parts
+            .next()
+            .unwrap_or("")
+            .parse()
+            .context("Invalid LND version")?;
+        let minor: u32 = parts
+            .next()
+            .unwrap_or("")
+            .parse()
+            .context("Invalid LND version")?;
+        ensure!(
+            major > 0 || minor >= 21,
+            "This fee-bump interface requires LND 0.21 or newer"
+        );
+        let history = lnd(&client, &macaroon, "/v1/transactions", None).await?;
+        let txs = array(&history, "transactions")?;
+        let tx = txs
+            .iter()
+            .find(|t| t["tx_hash"] == txid)
+            .context("Transaction is not in this wallet")?;
+        ensure!(
+            tx["num_confirmations"].as_i64() == Some(0),
+            "This transaction is no longer pending"
+        );
+        let entry: Value = self
+            .bitcoin_rpc_call(&client, "getmempoolentry", &[json!(txid)])
+            .await
+            .context("Transaction is not currently in the node's mempool")?;
+        ensure!(
+            number(&entry["descendantcount"])? == 1,
+            "This transaction already has a child; open the child's Bump options instead"
+        );
+        let pending = lnd(&client, &macaroon, "/v2/wallet/sweeps/pending", None).await?;
+        let sweeps = array(&pending, "pending_sweeps")?;
+        let published = lnd(
+            &client,
+            &macaroon,
+            "/v2/wallet/sweeps?verbose=false&start_height=-1",
+            None,
+        )
+        .await?;
+        let is_sweep = published["transaction_ids"]["transaction_ids"]
+            .as_array()
+            .is_some_and(|ids| ids.iter().any(|id| id == txid));
+        let outputs = array(tx, "output_details")?;
+        ensure!(
+            tx["amount"]
+                .as_str()
+                .and_then(|v| v.parse::<i64>().ok())
+                .or_else(|| tx["amount"].as_i64())
+                .is_some_and(|v| v < 0),
+            "Bump is available for outgoing payments and wallet fee sweeps"
+        );
+        let (
+            method,
+            input_txid,
+            input_index,
+            input_sats,
+            parent_txid,
+            parent_size,
+            parent_fee,
+            old_fee,
+            size,
+            recipient_sats,
+        ) = if is_sweep {
+            // Only a simple wallet CPFP sweep is replaceable here. Anchor/HTLC,
+            // batched sweeps and arbitrary signed payments need different previews.
+            let raw: Value = self
+                .bitcoin_rpc_call(&client, "getrawtransaction", &[json!(txid), json!(true)])
+                .await?;
+            let inputs = array(&raw, "vin")?;
+            ensure!(
+                inputs.len() == 1 && outputs.len() == 1 && outputs[0]["is_our_address"] == true,
+                "RBF for batched or channel sweeps is not supported here yet"
+            );
+            let input_txid = inputs[0]["txid"]
+                .as_str()
+                .context("Missing sweep input")?
+                .to_string();
+            let index = u32::try_from(number(&inputs[0]["vout"])?)?;
+            ensure!(
+                sweeps.len() == 1 && outpoint_matches(&sweeps[0]["outpoint"], &input_txid, index),
+                "RBF is unavailable while other wallet sweeps are active"
+            );
+            let parent = txs
+                .iter()
+                .find(|t| t["tx_hash"] == input_txid)
+                .context("Sweep parent is unavailable")?;
+            let parent_output = array(parent, "output_details")?
+                .iter()
+                .find(|o| {
+                    number(&o["output_index"]).ok() == Some(index as u64)
+                        && o["is_our_address"] == true
+                })
+                .context("RBF requires a wallet-owned change input")?;
+            let parent_entry: Value = self
+                .bitcoin_rpc_call(&client, "getmempoolentry", &[json!(input_txid)])
+                .await
+                .context("Only unconfirmed CPFP sweep replacements are supported here")?;
+            ensure!(
+                number(&parent_entry["ancestorcount"])? == 1
+                    && number(&parent_entry["descendantcount"])? == 2,
+                "Complex sweep package cannot be quoted safely"
+            );
+            let recipients = recipient_amount(parent)?;
+            (
+                "rbf",
+                input_txid.clone(),
+                index,
+                number(&parent_output["amount"])?,
+                input_txid,
+                number(&parent_entry["vsize"])?,
+                btc_sats(&parent_entry["fees"]["base"])?,
+                btc_sats(&entry["fees"]["base"])?,
+                sweep_size(parent_output)?.max(number(&entry["vsize"])?),
+                recipients,
+            )
+        } else {
+            ensure!(
+                sweeps.is_empty(),
+                "Another wallet sweep is active; wait for it before creating a CPFP bump"
+            );
+            ensure!(
+                number(&entry["ancestorcount"])? == 1,
+                "Fee bumping a chain of unconfirmed payments is not supported yet"
+            );
+            let unspent = lnd(
+                &client,
+                &macaroon,
+                "/v2/wallet/utxos",
+                Some(json!({"unconfirmed_only":true})),
+            )
+            .await?;
+            let utxos = array(&unspent, "utxos")?;
+            let leases = lnd(
+                &client,
+                &macaroon,
+                "/v2/wallet/utxos/leases",
+                Some(json!({})),
+            )
+            .await?;
+            let locked = array(&leases, "locked_utxos")?;
+            let output = outputs
+                .iter()
+                .filter(|o| o["is_our_address"] == true && sweep_size(o).is_ok())
+                .filter(|o| {
+                    number(&o["output_index"]).ok().is_some_and(|i| {
+                        utxos
+                            .iter()
+                            .any(|u| outpoint_matches(&u["outpoint"], txid, i as u32))
+                            && !locked
+                                .iter()
+                                .any(|u| outpoint_matches(&u["outpoint"], txid, i as u32))
+                    })
+                })
+                .max_by_key(|o| number(&o["amount"]).unwrap_or(0))
+                .context(
+                    "RBF is unavailable for this payment. CPFP needs spendable wallet-owned change",
+                )?;
+            let index = u32::try_from(number(&output["output_index"])?)?;
+            let available: Value = self
+                .bitcoin_rpc_call(
+                    &client,
+                    "gettxout",
+                    &[json!(txid), json!(index), json!(true)],
+                )
+                .await?;
+            ensure!(
+                available.is_object()
+                    && number(&available["confirmations"])? == 0
+                    && btc_sats(&available["value"])? == number(&output["amount"])?,
+                "Change is no longer available"
+            );
+            (
+                "cpfp",
+                txid.to_string(),
+                index,
+                number(&output["amount"])?,
+                txid.to_string(),
+                number(&entry["vsize"])?,
+                btc_sats(&entry["fees"]["base"])?,
+                0,
+                sweep_size(output)?,
+                recipient_amount(tx)?,
+            )
+        };
+        let mempool: Value = self
+            .bitcoin_rpc_call(&client, "getmempoolinfo", &[])
+            .await?;
+        let relay = btc_sats(&mempool["incrementalrelayfee"])?
+            .div_ceil(1000)
+            .max(1);
+        let floor = btc_sats(&mempool["mempoolminfee"])?
+            .max(btc_sats(&mempool["minrelaytxfee"])?)
+            .div_ceil(1000)
+            .max(1);
+        let rate = match custom_rate {
+            Some(rate) => {
+                ensure!(
+                    rate >= floor,
+                    "Custom rate is below the current mempool minimum"
+                );
+                rate
+            }
+            None => {
+                let estimate = lnd(&client, &macaroon, "/v2/wallet/estimatefee/1", None).await?;
+                number(&estimate["sat_per_kw"])?.div_ceil(250).max(floor)
+            }
+        };
+        let budget = fee_budget(
+            rate,
+            parent_size,
+            parent_fee,
+            size,
+            old_fee,
+            relay.max(floor),
+            input_sats,
+        )
+        .map_err(|error| {
+            if error.to_string().contains("Not enough wallet change") {
+                quote_budget_error(
+                    rate,
+                    parent_size,
+                    parent_fee,
+                    size,
+                    old_fee,
+                    relay.max(floor),
+                    input_sats,
+                )
+            } else {
+                error
+            }
+        })?;
+        let tip: String = self
+            .bitcoin_rpc_call(&client, "getbestblockhash", &[])
+            .await?;
+        Ok(Plan {
+            txid: txid.to_string(),
+            method: method.into(),
+            input_txid,
+            input_index,
+            parent_txid,
+            recipient_sats,
+            rate_sat_vb: rate,
+            current_fee_sats: parent_fee + old_fee,
+            additional_fee_sats: budget - old_fee,
+            total_fee_sats: parent_fee + budget,
+            budget_sats: budget,
+            input_sats,
+            parent_vsize: parent_size,
+            sweep_vsize_bound: size,
+            tip,
+        })
+    }
+
+    pub(in crate::api::rpc) async fn handle_lnd_bump_quote(
+        &self,
+        params: Option<Value>,
+    ) -> Result<Value> {
+        let p = params.unwrap_or_default();
+        let txid = txid_param(&p)?;
+        let path = self
+            .config
+            .data_dir
+            .join("wallet/fee-bumps")
+            .join(format!("{txid}.json"));
+        ensure!(
+            !path.try_exists()?,
+            "A bump was already submitted for this transaction. Check its status"
+        );
+        let custom = p
+            .get("sat_per_vbyte")
+            .map(|v| v.as_u64().context("Custom rate must be a whole number"))
+            .transpose()?;
+        if let Some(rate) = custom {
+            ensure!(
+                (1..=5000).contains(&rate),
+                "Custom rate must be 1–5000 sat/vB"
+            );
+        }
+        let plan = self.bump_plan(&txid, custom).await?;
+        let quote = Quote {
+            quote_id: uuid::Uuid::new_v4().to_string(),
+            expires_at: now() + QUOTE_SECONDS,
+            custom_rate: custom,
+            plan,
+        };
+        let mut quotes = QUOTES.lock().await;
+        quotes.retain(|_, q| q.expires_at > now());
+        ensure!(quotes.len() < 128, "Too many fee quotes; try again shortly");
+        quotes.insert(quote.quote_id.clone(), quote.clone());
+        Ok(serde_json::to_value(quote)?)
+    }
+
+    pub(in crate::api::rpc) async fn handle_lnd_bump_submit(
+        &self,
+        params: Option<Value>,
+    ) -> Result<Value> {
+        let p = params.unwrap_or_default();
+        let txid = txid_param(&p)?;
+        let _guard = SUBMIT.lock().await;
+        let path = self
+            .config
+            .data_dir
+            .join("wallet/fee-bumps")
+            .join(format!("{txid}.json"));
+        if path.try_exists()? {
+            return self
+                .handle_lnd_bump_status(Some(json!({"txid":txid})))
+                .await;
+        }
+        let id = p["quote_id"]
+            .as_str()
+            .context("A reviewed fee quote is required")?;
+        let quote = QUOTES
+            .lock()
+            .await
+            .get(id)
+            .cloned()
+            .context("Quote expired; review the fee again")?;
+        ensure!(
+            quote.plan.txid == txid && quote.expires_at > now(),
+            "Quote expired; review the fee again"
+        );
+        let fresh = self.bump_plan(&txid, quote.custom_rate).await?;
+        validate_quote(&quote, &fresh, now())?;
+        let op = Operation {
+            quote: quote.clone(),
+            status: "unknown".into(),
+            message: "Submission recorded; checking the wallet. Do not submit another bump.".into(),
+        };
+        reserve(&path, &op).await?;
+        QUOTES.lock().await.remove(id);
+        let (client, macaroon) = self.lnd_client().await?;
+        // At a one-block deadline LND may spend ALL this explicitly previewed
+        // budget. It is always below input value, so no extra funding is requested.
+        let result = lnd(
+            &client,
+            &macaroon,
+            "/v2/wallet/bumpfee",
+            Some(bump_body(&fresh)),
+        )
+        .await;
+        // Keep the write-ahead record even for an RPC error: a lost response can
+        // conceal an accepted bump. Status reconciles from wallet/mempool evidence.
+        match result {
+            Ok(_) => Ok(
+                json!({"status":"registered", "message":"Bump registered with the wallet. Waiting for broadcast.", "quote":quote}),
+            ),
+            Err(_) => Ok(
+                json!({"status":"unknown", "message":"The wallet response was not confirmed. Check status; do not submit again.", "quote":quote}),
+            ),
+        }
+    }
+
+    pub(in crate::api::rpc) async fn handle_lnd_bump_status(
+        &self,
+        params: Option<Value>,
+    ) -> Result<Value> {
+        let txid = txid_param(&params.unwrap_or_default())?;
+        let path = self
+            .config
+            .data_dir
+            .join("wallet/fee-bumps")
+            .join(format!("{txid}.json"));
+        let bytes = match tokio::fs::read(path).await {
+            Ok(b) => b,
+            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
+                return Ok(json!({"status":"none"}))
+            }
+            Err(e) => return Err(e.into()),
+        };
+        let op: Operation = serde_json::from_slice(&bytes)
+            .context("Bump receipt needs recovery; do not resubmit")?;
+        let (client, macaroon) = self.lnd_client().await?;
+        let history = lnd(&client, &macaroon, "/v1/transactions", None).await?;
+        let plan = &op.quote.plan;
+        let input = format!("{}:{}", plan.input_txid, plan.input_index);
+        let mut candidates: Vec<&Value> = array(&history, "transactions")?
+            .iter()
+            .filter(|t| {
+                t["tx_hash"] != txid
+                    && t["output_details"].as_array().is_some_and(|outputs| {
+                        !outputs.is_empty() && outputs.iter().all(|o| o["is_our_address"] == true)
+                    })
+                    && t["previous_outpoints"]
+                        .as_array()
+                        .is_some_and(|inputs| inputs.iter().any(|i| i["outpoint"] == input))
+            })
+            .collect();
+        candidates.sort_by_key(|t| std::cmp::Reverse(number(&t["time_stamp"]).unwrap_or(0)));
+        for t in candidates {
+            let id = t["tx_hash"]
+                .as_str()
+                .context("Missing bump transaction ID")?;
+            let confirmed = t["num_confirmations"].as_i64().unwrap_or(0) > 0;
+            let accepted = if confirmed {
+                false
+            } else {
+                self.bitcoin_rpc_call::<Value>(&client, "getmempoolentry", &[json!(id)])
+                    .await
+                    .is_ok()
+            };
+            if confirmed || accepted {
+                return Ok(json!({"status":if confirmed {"confirmed"} else {"mempool"},
+                    "message":if confirmed {"Fee bump confirmed."} else {"Fee bump accepted in the node's mempool; awaiting confirmation."},
+                    "bump_txid":id,"confirmations":t["num_confirmations"],"actual_sweep_fee_sats":number(&t["total_fees"])?,"quote":op.quote}));
+            }
+        }
+        let pending = lnd(&client, &macaroon, "/v2/wallet/sweeps/pending", None).await?;
+        let registered = array(&pending, "pending_sweeps")?.iter().any(|s| {
+            outpoint_matches(&s["outpoint"], &plan.input_txid, plan.input_index)
+                && number(&s["budget"]).ok() == Some(plan.budget_sats)
+                && number(&s["requested_sat_per_vbyte"]).ok() == Some(plan.rate_sat_vb)
+        });
+        Ok(
+            json!({"status":if registered {"registered"} else {"unknown"},
+            "message":if registered {"Bump registered; waiting for a verified broadcast."} else {"Submission outcome is unknown. Do not submit again; check wallet status."}, "quote":op.quote}),
+        )
+    }
+}
+fn recipient_amount(tx: &Value) -> Result<u64> {
+    array(tx, "output_details")?
+        .iter()
+        .filter(|o| o["is_our_address"] == false)
+        .try_fold(0u64, |sum, o| {
+            sum.checked_add(number(&o["amount"])?)
+                .context("Recipient amount overflow")
+        })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    fn sample_plan() -> Plan {
+        serde_json::from_value(json!({"txid":"a","method":"cpfp","input_txid":"a","input_index":0,"parent_txid":"a","recipient_sats":161650,"rate_sat_vb":3,"current_fee_sats":144,"additional_fee_sats":618,"total_fee_sats":762,"budget_sats":618,"input_sats":21126,"parent_vsize":142,"sweep_vsize_bound":112,"tip":"tip"})).unwrap()
+    }
+    #[test]
+    fn history_requires_owned_simple_fee_only_child() {
+        let plan = sample_plan();
+        let tx = json!({"tx_hash":"b".repeat(64),"amount":"-200","total_fees":"200",
+            "previous_outpoints":[{"outpoint":"a:0","is_our_output":true}],
+            "output_details":[{"is_our_address":true}]});
+        assert!(fee_child_matches(&tx, &plan));
+        for bad in [
+            json!({"amount":"-201"}),
+            json!({"amount":"200"}),
+            json!({"total_fees":"0"}),
+            json!({"previous_outpoints":[{"outpoint":"a:1","is_our_output":true}]}),
+            json!({"previous_outpoints":[{"outpoint":"a:0","is_our_output":false}]}),
+            json!({"previous_outpoints":[{"outpoint":"a:0","is_our_output":true},{"outpoint":"c:0","is_our_output":true}]}),
+            json!({"output_details":[{"is_our_address":false}]}),
+            json!({"output_details":[]}),
+            json!({"tx_hash":"../../invalid"}),
+        ] {
+            let mut changed = tx.clone();
+            for (key, value) in bad.as_object().unwrap() {
+                changed[key] = value.clone();
+            }
+            assert!(!fee_child_matches(&changed, &plan), "{bad}");
+        }
+    }
+    #[test]
+    fn stale_quotes_cannot_silently_change_approved_fee_or_transaction() {
+        let plan = sample_plan();
+        let q = Quote {
+            quote_id: "q".into(),
+            expires_at: 100,
+            custom_rate: None,
+            plan: plan.clone(),
+        };
+        assert!(validate_quote(&q, &plan, 99).is_ok());
+        assert!(validate_quote(&q, &plan, 100).is_err());
+        let mut changed = plan.clone();
+        changed.budget_sats += 1;
+        assert!(validate_quote(&q, &changed, 99).is_err());
+        changed = plan.clone();
+        changed.input_index += 1;
+        assert!(validate_quote(&q, &changed, 99).is_err());
+        changed = plan.clone();
+        changed.recipient_sats -= 1;
+        assert!(validate_quote(&q, &changed, 99).is_err());
+        changed = plan.clone();
+        changed.tip = "new block".into();
+        assert!(validate_quote(&q, &changed, 99).is_err());
+    }
+    #[test]
+    fn mutation_always_has_explicit_budget_and_does_not_send_a_second_payment() {
+        assert_eq!(
+            bump_body(&sample_plan()),
+            json!({"outpoint":{"txid_str":"a","output_index":0},"sat_per_vbyte":"3","budget":"618","deadline_delta":1,"immediate":true})
+        );
+        let mut rbf = sample_plan();
+        rbf.method = "rbf".into();
+        rbf.txid = "child".into();
+        // RBF uses the already-registered input, not the child's output.
+        assert_eq!(bump_body(&rbf)["outpoint"]["txid_str"], "a");
+    }
+    #[test]
+    fn outpoint_ownership_and_recipient_exclude_wallet_change() {
+        assert!(outpoint_matches(
+            &json!({"txid_str":"a","output_index":2}),
+            "a",
+            2
+        ));
+        assert!(!outpoint_matches(
+            &json!({"txid_str":"b","output_index":2}),
+            "a",
+            2
+        ));
+        assert!(!outpoint_matches(
+            &json!({"txid_str":"a","output_index":3}),
+            "a",
+            2
+        ));
+        assert_eq!(recipient_amount(&json!({"output_details":[{"is_our_address":true,"amount":"21126"},{"is_our_address":false,"amount":"161650"}]})).unwrap(), 161650);
+        assert!(recipient_amount(
+            &json!({"output_details":[{"is_our_address":false,"amount":"bad"}]})
+        )
+        .is_err());
+    }
+    #[test]
+    fn cpfp_budget_covers_parent_and_preserves_change() {
+        assert_eq!(fee_budget(3, 142, 144, 112, 0, 1, 21126).unwrap(), 618);
+        assert!(fee_budget(5000, 142, 144, 112, 0, 1, 21126).is_err());
+        assert!(fee_budget(0, 142, 144, 112, 0, 1, 21126).is_err());
+    }
+    #[test]
+    fn unaffordable_quote_explains_spendable_change_and_viable_rate() {
+        let suggested = highest_affordable_rate(5000, 142, 144, 112, 0, 1, 21126);
+        assert_eq!(suggested, Some(79));
+        let error = quote_budget_error(5000, 142, 144, 112, 0, 1, 21126).to_string();
+        assert!(error.contains("at most 20126 sats is spendable"));
+        assert!(error.contains("Try 79 sat/vB or lower"));
+    }
+    #[test]
+    fn no_affordable_rate_is_reported_without_mutating_the_output() {
+        let error = quote_budget_error(10, 142, 144, 112, 9_000, 1, 10_000).to_string();
+        assert!(error.contains("at most 9000 sats is spendable"));
+        assert!(error.contains("No fee rate can currently fit this output"));
+    }
+    #[test]
+    fn rbf_pays_incremental_relay_cost_and_counts_only_extra_cost() {
+        let fee = fee_budget(3, 142, 144, 112, 650, 1, 21126).unwrap();
+        assert_eq!(fee, 763);
+        assert_eq!(fee - 650, 113);
+    }
+    #[test]
+    fn unsupported_outputs_and_malformed_ids_fail_closed() {
+        assert!(sweep_size(&json!({"output_type":"SCRIPT_TYPE_WITNESS_V0_SCRIPT_HASH"})).is_err());
+        assert!(txid_param(&json!({"txid":"../../file"})).is_err());
+        assert!(number(&json!(-1)).is_err());
+        assert!(btc_sats(&json!(-0.1)).is_err());
+        assert_eq!(btc_sats(&json!(0.00000650)).unwrap(), 650);
+    }
+    #[tokio::test]
+    async fn receipt_prevents_duplicate_submission_after_restart() {
+        let dir = std::env::temp_dir().join(uuid::Uuid::new_v4().to_string());
+        let path = dir.join("receipt.json");
+        let plan: Plan = serde_json::from_value(json!({"txid":"a","method":"cpfp","input_txid":"a","input_index":0,"parent_txid":"a","recipient_sats":1000,"rate_sat_vb":3,"current_fee_sats":144,"additional_fee_sats":618,"total_fee_sats":762,"budget_sats":618,"input_sats":21126,"parent_vsize":142,"sweep_vsize_bound":112,"tip":"tip"})).unwrap();
+        let op = Operation {
+            quote: Quote {
+                quote_id: "q".into(),
+                expires_at: now() + 60,
+                custom_rate: None,
+                plan,
+            },
+            status: "unknown".into(),
+            message: "pending".into(),
+        };
+        reserve(&path, &op).await.unwrap();
+        assert!(reserve(&path, &op).await.is_err());
+        let restored: Operation =
+            serde_json::from_slice(&tokio::fs::read(&path).await.unwrap()).unwrap();
+        assert_eq!(restored.quote.plan.budget_sats, 618);
+        tokio::fs::remove_dir_all(dir).await.unwrap();
+    }
+}

core/archipelago/src/api/rpc/lnd/fee_policy.rs

@@ -0,0 +1,120 @@
+//! Explicit on-chain fee choices retain priority; omitted choices target the next block.
+use anyhow::{ensure, Context, Result};
+use serde_json::Value;
+
+pub(super) const DEFAULT_TARGET: i64 = 1;
+
+pub(super) fn estimated_sat_per_vbyte(value: &Value) -> Result<u64> {
+    let per_kw = value["sat_per_kw"]
+        .as_u64()
+        .or_else(|| value["sat_per_kw"].as_str().and_then(|s| s.parse().ok()))
+        .context("Next-block fee estimate is unavailable")?;
+    let rate = per_kw.div_ceil(250);
+    ensure!(
+        (1..=5000).contains(&rate),
+        "Next-block fee estimate is outside supported bounds; choose an explicit fee"
+    );
+    Ok(rate)
+}
+
+pub(super) fn fee_options(params: &Value) -> Result<(Option<i64>, Option<i64>)> {
+    let integer = |key: &str, max: i64| -> Result<Option<i64>> {
+        match params.get(key) {
+            None | Some(Value::Null) => Ok(None),
+            Some(value) => {
+                let n = value
+                    .as_i64()
+                    .with_context(|| format!("{key} must be a positive whole number"))?;
+                ensure!((1..=max).contains(&n), "{key} must be between 1 and {max}");
+                Ok(Some(n))
+            }
+        }
+    };
+    let target = integer("target_conf", 1008)?;
+    let rate = integer("sat_per_vbyte", 5000)?;
+    ensure!(
+        target.is_none() || rate.is_none(),
+        "Specify either target_conf or sat_per_vbyte, not both"
+    );
+    Ok((
+        if rate.is_none() {
+            Some(target.unwrap_or(DEFAULT_TARGET))
+        } else {
+            None
+        },
+        rate,
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn estimates_round_up_and_missing_or_extreme_estimates_fail_closed() {
+        assert_eq!(
+            estimated_sat_per_vbyte(&json!({"sat_per_kw":"501"})).unwrap(),
+            3
+        );
+        assert_eq!(
+            estimated_sat_per_vbyte(&json!({"sat_per_kw":250})).unwrap(),
+            1
+        );
+        for v in [
+            json!({}),
+            json!({"sat_per_kw":0}),
+            json!({"sat_per_kw":-1}),
+            json!({"sat_per_kw":1250001}),
+        ] {
+            assert!(estimated_sat_per_vbyte(&v).is_err());
+        }
+    }
+
+    #[test]
+    fn next_block_default_preserves_explicit_slower_and_custom_choices() {
+        assert_eq!(fee_options(&json!({})).unwrap(), (Some(1), None));
+        assert_eq!(
+            fee_options(&json!({"target_conf":null})).unwrap(),
+            (Some(1), None)
+        );
+        for target in [1, 3, 6, 144, 1008] {
+            assert_eq!(
+                fee_options(&json!({"target_conf":target})).unwrap(),
+                (Some(target), None)
+            );
+        }
+        for rate in [1, 17, 5000] {
+            assert_eq!(
+                fee_options(&json!({"sat_per_vbyte":rate})).unwrap(),
+                (None, Some(rate))
+            );
+        }
+    }
+
+    #[test]
+    fn malformed_explicit_fees_never_silently_become_fast() {
+        for value in [
+            json!(0),
+            json!(-1),
+            json!(1.5),
+            json!("6"),
+            json!(true),
+            json!({}),
+            json!(1009),
+        ] {
+            assert!(fee_options(&json!({"target_conf":value})).is_err());
+        }
+        for value in [
+            json!(0),
+            json!(-1),
+            json!(1.5),
+            json!("6"),
+            json!(true),
+            json!(5001),
+        ] {
+            assert!(fee_options(&json!({"sat_per_vbyte":value})).is_err());
+        }
+        assert!(fee_options(&json!({"target_conf":1,"sat_per_vbyte":2})).is_err());
+    }
+}

core/archipelago/src/api/rpc/lnd/info.rs

@@ -73,7 +73,86 @@ struct LndChannelBalanceResponse {
     pending_open_local_balance: Option<LndAmount>,
 }
 
+/// Reject unavailable LND data before it can be decoded as an empty, zero wallet.
+async fn get_lnd_json<T: serde::de::DeserializeOwned>(
+    client: &reqwest::Client,
+    url: &str,
+    macaroon_hex: &str,
+) -> Result<T> {
+    client
+        .get(url)
+        .header("Grpc-Metadata-macaroon", macaroon_hex)
+        .send()
+        .await
+        .context("LND is unavailable; balance could not be checked")?
+        .error_for_status()
+        .context("LND is not ready; balance could not be checked")?
+        .json()
+        .await
+        .context("LND returned invalid wallet data")
+}
+
+fn checked_balances(
+    wallet: LndBalanceResponse,
+    channels: LndChannelBalanceResponse,
+) -> Result<(i64, i64, i64)> {
+    fn sats(value: Option<String>) -> Result<i64> {
+        let value = value.context("LND omitted a balance; balance is unavailable")?;
+        let amount: i64 = value.parse().context("LND returned an invalid balance")?;
+        anyhow::ensure!(amount >= 0, "LND returned a negative balance");
+        Ok(amount)
+    }
+    Ok((
+        sats(wallet.total_balance)?,
+        sats(channels.local_balance.and_then(|a| a.sat))?,
+        sats(channels.pending_open_local_balance.and_then(|a| a.sat))?,
+    ))
+}
+
+fn bitcoin_wait_state(
+    installed: bool,
+    running: bool,
+    fresh: bool,
+    ibd: Option<bool>,
+) -> (&'static str, &'static str) {
+    if !installed {
+        ("waiting_install", "Waiting for Bitcoin to be installed")
+    } else if !running {
+        ("waiting_start", "Waiting for Bitcoin to start")
+    } else if !fresh || ibd.is_none() {
+        ("waiting_start", "Waiting for Bitcoin to start")
+    } else if ibd == Some(true) {
+        ("waiting_sync", "Waiting for Bitcoin to sync")
+    } else {
+        ("bitcoin_ready", "Bitcoin is ready")
+    }
+}
+
 impl RpcHandler {
+    pub(crate) async fn handle_lnd_readiness(&self) -> serde_json::Value {
+        let (data, _) = self.state_manager.get_snapshot().await;
+        if !data.server_info.status_info.containers_scanned {
+            return serde_json::json!({"state":"checking", "message":"Checking Bitcoin availability"});
+        }
+        let nodes: Vec<_> = ["bitcoin-core", "bitcoin-knots", "bitcoin"]
+            .iter()
+            .filter_map(|id| data.package_data.get(*id))
+            .collect();
+        let installed = !nodes.is_empty();
+        let running = nodes
+            .iter()
+            .any(|p| p.state == crate::data_model::PackageState::Running);
+        let bitcoin = crate::bitcoin_status::get_bitcoin_status().await;
+        let ibd = bitcoin
+            .blockchain_info
+            .as_ref()
+            .and_then(|v| v.get("initialblockdownload"))
+            .and_then(|v| v.as_bool());
+        let (state, message) =
+            bitcoin_wait_state(installed, running, bitcoin.ok && !bitcoin.stale, ibd);
+        serde_json::json!({"state": state, "message": message})
+    }
+
     pub(in crate::api::rpc) async fn handle_lnd_getinfo(&self) -> Result<serde_json::Value> {
         let macaroon_bytes = read_lnd_admin_macaroon().await?;
         let macaroon_hex = hex::encode(&macaroon_bytes);
@@ -85,45 +164,26 @@ impl RpcHandler {
             .build()
             .context("Failed to create HTTP client")?;
 
-        let get_info: LndGetInfoResponse = client
-            .get(format!("{LND_REST_BASE_URL}/v1/getinfo"))
-            .header("Grpc-Metadata-macaroon", &macaroon_hex)
-            .send()
-            .await
-            .context("LND REST connection failed")?
-            .json()
-            .await
-            .context("Failed to parse LND getinfo response")?;
-
-        let channel_balance: LndChannelBalanceResponse = match client
-            .get(format!("{LND_REST_BASE_URL}/v1/balance/channels"))
-            .header("Grpc-Metadata-macaroon", &macaroon_hex)
-            .send()
-            .await
-        {
-            Ok(resp) => resp.json().await.unwrap_or(LndChannelBalanceResponse {
-                local_balance: None,
-                pending_open_local_balance: None,
-            }),
-            Err(_) => LndChannelBalanceResponse {
-                local_balance: None,
-                pending_open_local_balance: None,
-            },
-        };
-
-        let wallet_balance: LndBalanceResponse = match client
-            .get(format!("{LND_REST_BASE_URL}/v1/balance/blockchain"))
-            .header("Grpc-Metadata-macaroon", &macaroon_hex)
-            .send()
-            .await
-        {
-            Ok(resp) => resp.json().await.unwrap_or(LndBalanceResponse {
-                total_balance: None,
-            }),
-            Err(_) => LndBalanceResponse {
-                total_balance: None,
-            },
-        };
+        let get_info: LndGetInfoResponse = get_lnd_json(
+            &client,
+            &format!("{LND_REST_BASE_URL}/v1/getinfo"),
+            &macaroon_hex,
+        )
+        .await?;
+        let channel_balance: LndChannelBalanceResponse = get_lnd_json(
+            &client,
+            &format!("{LND_REST_BASE_URL}/v1/balance/channels"),
+            &macaroon_hex,
+        )
+        .await?;
+        let wallet_balance: LndBalanceResponse = get_lnd_json(
+            &client,
+            &format!("{LND_REST_BASE_URL}/v1/balance/blockchain"),
+            &macaroon_hex,
+        )
+        .await?;
+        let (balance_sats, channel_balance_sats, pending_open_balance) =
+            checked_balances(wallet_balance, channel_balance)?;
 
         let (identity_pubkey, uris) = map_identity(&get_info);
 
@@ -135,18 +195,9 @@ impl RpcHandler {
             num_peers: get_info.num_peers.unwrap_or(0),
             synced_to_chain: get_info.synced_to_chain.unwrap_or(false),
             block_height: get_info.block_height.unwrap_or(0),
-            balance_sats: wallet_balance
-                .total_balance
-                .and_then(|s| s.parse().ok())
-                .unwrap_or(0),
-            channel_balance_sats: channel_balance
-                .local_balance
-                .and_then(|a| a.sat.and_then(|s| s.parse().ok()))
-                .unwrap_or(0),
-            pending_open_balance: channel_balance
-                .pending_open_local_balance
-                .and_then(|a| a.sat.and_then(|s| s.parse().ok()))
-                .unwrap_or(0),
+            balance_sats,
+            channel_balance_sats,
+            pending_open_balance,
         };
 
         Ok(serde_json::to_value(info)?)
@@ -268,6 +319,76 @@ impl RpcHandler {
 mod tests {
     use super::*;
 
+    #[test]
+    fn unavailable_balances_are_not_zero() {
+        for body in [r#"{}"#, r#"{"code":14,"message":"wallet locked"}"#] {
+            assert!(checked_balances(
+                serde_json::from_str(body).unwrap(),
+                serde_json::from_str(body).unwrap(),
+            )
+            .is_err());
+        }
+        for value in ["bad", "-1", "9223372036854775808"] {
+            let wallet = LndBalanceResponse {
+                total_balance: Some(value.into()),
+            };
+            let channels = serde_json::from_str(
+                r#"{"local_balance":{"sat":"5"},"pending_open_local_balance":{"sat":"0"}}"#,
+            )
+            .unwrap();
+            assert!(checked_balances(wallet, channels).is_err());
+        }
+    }
+
+    #[test]
+    fn verified_zero_and_nonzero_balances_survive() {
+        for expected in [0, 42] {
+            let wallet = LndBalanceResponse {
+                total_balance: Some(expected.to_string()),
+            };
+            let channels = serde_json::from_value(serde_json::json!({
+                "local_balance":{"sat":expected.to_string()},
+                "pending_open_local_balance":{"sat":"0"}
+            }))
+            .unwrap();
+            assert_eq!(
+                checked_balances(wallet, channels).unwrap(),
+                (expected, expected, 0)
+            );
+        }
+    }
+
+    #[tokio::test]
+    async fn locked_wallet_http_response_is_not_successful_getinfo() {
+        use tokio::io::{AsyncReadExt, AsyncWriteExt};
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let addr = listener.local_addr().unwrap();
+        let server = tokio::spawn(async move {
+            let (mut stream, _) = listener.accept().await.unwrap();
+            let mut buf = [0; 2048];
+            stream.read(&mut buf).await.unwrap();
+            let body =
+                r#"{"code":9,"message":"wallet locked, unlock it to enable full RPC access"}"#;
+            stream.write_all(format!(
+                "HTTP/1.1 503 Service Unavailable\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
+                body.len(), body
+            ).as_bytes()).await.unwrap();
+        });
+        let client = reqwest::Client::builder()
+            .no_proxy()
+            .timeout(std::time::Duration::from_secs(2))
+            .build()
+            .unwrap();
+        assert!(get_lnd_json::<LndGetInfoResponse>(
+            &client,
+            &format!("http://{addr}/v1/getinfo"),
+            "test"
+        )
+        .await
+        .is_err());
+        server.await.unwrap();
+    }
+
     /// A real compressed secp256k1 pubkey shape: 66 hex characters.
     const GOOD_PUBKEY: &str = "03a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90";
 
@@ -341,3 +462,44 @@ mod tests {
         assert!(!is_valid_identity_pubkey(&"g".repeat(66)));
     }
 }
+
+#[cfg(test)]
+mod dependency_readiness_tests {
+    use super::bitcoin_wait_state;
+    #[test]
+    fn waiting_states_cover_install_start_sync_outage_and_recovery() {
+        assert_eq!(
+            bitcoin_wait_state(false, false, false, None).0,
+            "waiting_install"
+        );
+        assert_eq!(
+            bitcoin_wait_state(true, false, false, None).0,
+            "waiting_start"
+        );
+        assert_eq!(
+            bitcoin_wait_state(true, true, false, None).0,
+            "waiting_start"
+        );
+        assert_eq!(
+            bitcoin_wait_state(true, true, true, Some(true)).0,
+            "waiting_sync"
+        );
+        assert_eq!(
+            bitcoin_wait_state(true, true, true, Some(false)).0,
+            "bitcoin_ready"
+        );
+        // Previously synced cached information must not hide a current outage.
+        assert_eq!(
+            bitcoin_wait_state(true, true, false, Some(false)).0,
+            "waiting_start"
+        );
+        assert_eq!(
+            bitcoin_wait_state(true, true, true, None).0,
+            "waiting_start"
+        );
+        assert_eq!(
+            bitcoin_wait_state(true, true, true, Some(false)).0,
+            "bitcoin_ready"
+        );
+    }
+}

core/archipelago/src/api/rpc/lnd/mod.rs

@@ -1,6 +1,10 @@
 mod channels;
+pub(super) mod external_invoice;
+mod fee_bump;
+mod fee_policy;
 mod info;
 mod macaroons;
+pub(super) mod onchain_purchase;
 mod payments;
 mod seed_backup;
 mod wallet;
@@ -133,12 +137,36 @@ async fn stream_lnd_transactions(sm: &crate::state::StateManager) -> Result<()>
 /// RPC-unreachable and locked-wallet states are deliberately NOT handled
 /// here — container-down is crash-recovery's job, and unlocking needs the
 /// operator.
+fn bitcoin_ready_for_lnd_watchdog(status: &crate::bitcoin_status::BitcoinNodeStatus) -> bool {
+    status.ok
+        && !status.stale
+        && status.age_ms < 30_000
+        && status
+            .blockchain_info
+            .as_ref()
+            .and_then(|v| v.get("initialblockdownload"))
+            .and_then(|v| v.as_bool())
+            == Some(false)
+}
+
 pub(crate) fn spawn_lnd_health_watchdog() {
     tokio::spawn(async move {
         let mut bad_minutes: u32 = 0;
         let mut last_restart: Option<tokio::time::Instant> = None;
+        let mut last_height: Option<u64> = None;
         loop {
             tokio::time::sleep(std::time::Duration::from_secs(60)).await;
+            // Initial Bitcoin sync, warmup, and outages are dependencies to
+            // wait for, never evidence that LND is wedged. Do not accumulate
+            // restart pressure during a days-long initial block download.
+            let bitcoin = crate::bitcoin_status::get_bitcoin_status().await;
+            if !bitcoin_ready_for_lnd_watchdog(&bitcoin)
+                || crate::app_ops::lifecycle_op_in_flight("lnd")
+            {
+                bad_minutes = 0;
+                last_height = None;
+                continue;
+            }
             let Ok(bytes) = read_lnd_admin_macaroon().await else {
                 bad_minutes = 0; // no LND on this node (or not set up yet)
                 continue;
@@ -161,6 +189,10 @@ pub(crate) fn spawn_lnd_health_watchdog() {
                 bad_minutes = 0; // down/locked — not the wedge signature
                 continue;
             };
+            if !resp.status().is_success() {
+                bad_minutes = 0;
+                continue;
+            }
             let Ok(info) = resp.json::<serde_json::Value>().await else {
                 bad_minutes = 0;
                 continue;
@@ -182,7 +214,12 @@ pub(crate) fn spawn_lnd_health_watchdog() {
                     .get("num_pending_channels")
                     .and_then(|v| v.as_u64())
                     .unwrap_or(0);
-            let wedged = !synced || (channels > 0 && peers == 0);
+            let height = info.get("block_height").and_then(|v| v.as_u64());
+            let progressing = height
+                .zip(last_height)
+                .is_some_and(|(now, before)| now > before);
+            last_height = height;
+            let wedged = !progressing && (!synced || (channels > 0 && peers == 0));
             if !wedged {
                 bad_minutes = 0;
                 continue;
@@ -239,3 +276,31 @@ impl RpcHandler {
         Ok((client, macaroon_hex))
     }
 }
+
+#[cfg(test)]
+mod watchdog_dependency_tests {
+    use super::bitcoin_ready_for_lnd_watchdog;
+    use crate::bitcoin_status::BitcoinNodeStatus;
+    use serde_json::json;
+    #[test]
+    fn initial_sync_warmup_outage_stale_and_unknown_never_trigger_lnd_restart() {
+        let mut status = BitcoinNodeStatus::default();
+        assert!(!bitcoin_ready_for_lnd_watchdog(&status));
+        status.ok = true;
+        status.blockchain_info = Some(json!({"initialblockdownload":true}));
+        assert!(!bitcoin_ready_for_lnd_watchdog(&status));
+        status.blockchain_info = Some(json!({"initialblockdownload":false}));
+        assert!(bitcoin_ready_for_lnd_watchdog(&status));
+        status.stale = true;
+        assert!(!bitcoin_ready_for_lnd_watchdog(&status));
+        status.stale = false;
+        status.ok = false;
+        assert!(!bitcoin_ready_for_lnd_watchdog(&status));
+        status.ok = true;
+        status.age_ms = 30_000;
+        assert!(!bitcoin_ready_for_lnd_watchdog(&status));
+        status.age_ms = 0;
+        status.blockchain_info = Some(json!({}));
+        assert!(!bitcoin_ready_for_lnd_watchdog(&status));
+    }
+}

core/archipelago/src/api/rpc/lnd/payments.rs

@@ -34,6 +34,33 @@ fn payment_failure_reason(reason: &str) -> &'static str {
     }
 }
 
+/// Preserve terminal LND state as structured data. An RPC exception is an
+/// ambiguous outcome to callers and must not hide a verified unpaid failure.
+pub(super) fn router_payment_outcome(
+    payment: &serde_json::Value,
+    hash: &str,
+    decoded_amt: i64,
+) -> serde_json::Value {
+    let status = match payment.get("status").and_then(|value| value.as_str()) {
+        Some("SUCCEEDED") => "succeeded",
+        Some("FAILED") => "failed",
+        _ => "pending",
+    };
+    let mut result = serde_json::json!({
+        "status": status, "payment_hash": hash,
+        "amount_sats": json_i64(payment, "value_sat").unwrap_or(decoded_amt),
+    });
+    if status == "failed" {
+        result["failure_reason"] = serde_json::json!(payment_failure_reason(
+            payment
+                .get("failure_reason")
+                .and_then(|value| value.as_str())
+                .unwrap_or("")
+        ));
+    }
+    result
+}
+
 fn json_i64(value: &serde_json::Value, key: &str) -> Option<i64> {
     value.get(key).and_then(|v| {
         v.as_str()
@@ -190,33 +217,7 @@ impl RpcHandler {
             return Err(payment_error(msg));
         }
         let payment = body.get("result").unwrap_or(&body);
-        match payment.get("status").and_then(|v| v.as_str()).unwrap_or("") {
-            "SUCCEEDED" => {}
-            "FAILED" => {
-                let reason = payment
-                    .get("failure_reason")
-                    .and_then(|v| v.as_str())
-                    .map(payment_failure_reason)
-                    .unwrap_or("Payment failed");
-                return Err(anyhow::anyhow!("Payment failed: {reason}"));
-            }
-            _ => {
-                return Ok(serde_json::json!({
-                    "status": "pending",
-                    "payment_hash": decoded_hash,
-                    "amount_sats": decoded_amt,
-                }));
-            }
-        }
-
-        let amount_sat = json_i64(payment, "value_sat").unwrap_or(decoded_amt);
-        Ok(serde_json::json!({
-            "status": "succeeded",
-            // The decode endpoint returns the canonical hex hash used by our
-            // polling/list APIs. Router's bytes field is base64 in REST JSON.
-            "payment_hash": decoded_hash,
-            "amount_sats": amount_sat,
-        }))
+        Ok(router_payment_outcome(payment, &decoded_hash, decoded_amt))
     }
 
     /// Status of an outgoing Lightning payment by hex payment hash. Lets the
@@ -244,6 +245,10 @@ impl RpcHandler {
             .send()
             .await
             .context("LND REST connection failed")?;
+        anyhow::ensure!(
+            resp.status().is_success(),
+            "LND payment status is unavailable"
+        );
         let body: serde_json::Value = resp
             .json()
             .await
@@ -402,6 +407,9 @@ impl RpcHandler {
             }));
         }
 
+        self.group_fee_bump_history(raw_txs, &mut transactions, &client)
+            .await;
+
         // Sort by timestamp descending (most recent first)
         transactions.sort_by(|a, b| {
             let ta = a.get("time_stamp").and_then(|v| v.as_i64()).unwrap_or(0);
@@ -562,6 +570,29 @@ mod tests {
         assert!(payment_error(msg).to_string().contains("fresh invoice"));
     }
 
+    #[test]
+    fn terminal_router_failures_remain_distinct_from_ambiguous_payment_outcomes() {
+        let failed = router_payment_outcome(
+            &serde_json::json!({"status":"FAILED", "failure_reason":"FAILURE_REASON_INSUFFICIENT_BALANCE", "value_sat":"2"}),
+            &"ab".repeat(32),
+            0,
+        );
+        assert_eq!(failed["status"], "failed");
+        assert_eq!(failed["failure_reason"], "Insufficient channel balance");
+        assert_eq!(failed["amount_sats"], 2);
+        assert_eq!(failed["payment_hash"], "ab".repeat(32));
+        for status in ["IN_FLIGHT", "INITIATED", "UNKNOWN", ""] {
+            assert_eq!(
+                router_payment_outcome(&serde_json::json!({"status":status}), "", 2)["status"],
+                "pending"
+            );
+        }
+        assert_eq!(
+            router_payment_outcome(&serde_json::json!({"status":"SUCCEEDED"}), "", 2)["status"],
+            "succeeded"
+        );
+    }
+
     #[test]
     fn router_failure_reasons_are_actionable() {
         assert_eq!(

core/archipelago/src/api/rpc/lnd/wallet.rs

@@ -7,6 +7,57 @@ use zeroize::Zeroize;
 use super::LND_REST_BASE_URL;
 
 impl RpcHandler {
+    // Add inside api/rpc/lnd/wallet.rs RpcHandler impl; seller owns this lookup.
+    // Wire invoice-status response to this Value instead of reducing it to paid bool.
+    pub(crate) async fn content_invoice_lifecycle(
+        &self,
+        hash: &str,
+        content_id: &str,
+    ) -> Result<serde_json::Value> {
+        anyhow::ensure!(
+            hash.len() == 64 && hash.bytes().all(|c| c.is_ascii_hexdigit()),
+            "Invalid payment hash"
+        );
+        let hash = hash.to_ascii_lowercase();
+        let existing = crate::content_invoice::lookup(&self.config.data_dir, &hash).await?;
+        anyhow::ensure!(
+            existing.as_ref().is_none_or(|(id, _)| id == content_id),
+            "Invoice belongs to another content item"
+        );
+        if crate::content_invoice::is_paid_for(&self.config.data_dir, &hash, content_id).await {
+            return Ok(
+                serde_json::json!({"paid":true,"state":"settled","can_switch_method":false}),
+            );
+        }
+        let (client, macaroon_hex) = self.lnd_client().await?;
+        let response = client
+            .get(format!("{LND_REST_BASE_URL}/v1/invoice/{hash}"))
+            .header("Grpc-Metadata-macaroon", &macaroon_hex)
+            .send()
+            .await?;
+        if response.status() == reqwest::StatusCode::NOT_FOUND {
+            return Ok(
+                serde_json::json!({"paid":false,"state":"unknown","can_switch_method":false}),
+            );
+        }
+        let body: serde_json::Value = response.error_for_status()?.json().await?;
+        let price = content_invoice_amount(&body, content_id)
+            .context("Invoice content binding is unavailable")?;
+        anyhow::ensure!(
+            existing
+                .as_ref()
+                .is_none_or(|(_, expected)| *expected == price),
+            "Invoice price binding changed"
+        );
+        crate::content_invoice::record_pending(&self.config.data_dir, &hash, content_id, price)
+            .await?;
+        let result = content_invoice_lifecycle_body(&body, price);
+        if result["paid"] == true {
+            crate::content_invoice::mark_paid(&self.config.data_dir, &hash).await?;
+        }
+        Ok(result)
+    }
+
     /// Generate a new on-chain Bitcoin address.
     pub(in crate::api::rpc) async fn handle_lnd_newaddress(&self) -> Result<serde_json::Value> {
         let (client, macaroon_hex) = self.lnd_client().await.map_err(|e| {
@@ -124,28 +175,8 @@ impl RpcHandler {
             return Err(anyhow::anyhow!("Invalid Bitcoin address format"));
         }
 
-        // Fee control: either a confirmation target or an explicit fee rate
-        let target_conf = params.get("target_conf").and_then(|v| v.as_i64());
-        let sat_per_vbyte = params.get("sat_per_vbyte").and_then(|v| v.as_i64());
-        if target_conf.is_some() && sat_per_vbyte.is_some() {
-            return Err(anyhow::anyhow!(
-                "Invalid fee parameters: specify either target_conf or sat_per_vbyte, not both"
-            ));
-        }
-        if let Some(tc) = target_conf {
-            if !(1..=1008).contains(&tc) {
-                return Err(anyhow::anyhow!(
-                    "Invalid target_conf: must be between 1 and 1008 blocks"
-                ));
-            }
-        }
-        if let Some(rate) = sat_per_vbyte {
-            if !(1..=5000).contains(&rate) {
-                return Err(anyhow::anyhow!(
-                    "Invalid sat_per_vbyte: must be between 1 and 5000"
-                ));
-            }
-        }
+        // Omitted fees target the next block; explicit slower/custom choices win.
+        let (target_conf, sat_per_vbyte) = super::fee_policy::fee_options(&params)?;
 
         info!(
             addr = addr,
@@ -238,15 +269,12 @@ impl RpcHandler {
         if !(546..=21_000_000 * 100_000_000).contains(&amount) {
             return Err(anyhow::anyhow!("Invalid amount"));
         }
-        let target_conf = params
-            .get("target_conf")
-            .and_then(|v| v.as_i64())
-            .unwrap_or(6);
-        if !(1..=1008).contains(&target_conf) {
-            return Err(anyhow::anyhow!(
-                "Invalid target_conf: must be between 1 and 1008 blocks"
-            ));
-        }
+        let (target_conf, custom_rate) = super::fee_policy::fee_options(&params)?;
+        anyhow::ensure!(
+            custom_rate.is_none(),
+            "Fee estimation requires a confirmation target"
+        );
+        let target_conf = target_conf.unwrap_or(super::fee_policy::DEFAULT_TARGET);
 
         let (client, macaroon_hex) = self.lnd_client().await?;
 
@@ -453,6 +481,56 @@ impl RpcHandler {
         Ok(settled)
     }
 
+    /// Verify against LND at download time, rather than relying on a browser
+    /// having polled first. The memo/amount also recover pre-upgrade in-memory
+    /// entitlements after restart; unrelated invoices never unlock a file.
+    pub(crate) async fn settle_content_invoice(
+        &self,
+        hash: &str,
+        content_id: &str,
+    ) -> Result<bool> {
+        anyhow::ensure!(
+            hash.len() == 64 && hash.bytes().all(|c| c.is_ascii_hexdigit()),
+            "Invalid payment hash"
+        );
+        let hash = hash.to_ascii_lowercase();
+        let existing = crate::content_invoice::lookup(&self.config.data_dir, &hash).await?;
+        if let Some((id, _)) = &existing {
+            if id != content_id {
+                return Ok(false);
+            }
+        }
+        if crate::content_invoice::is_paid_for(&self.config.data_dir, &hash, content_id).await {
+            return Ok(true);
+        }
+        let (client, macaroon_hex) = self.lnd_client().await?;
+        let response = client
+            .get(format!("{LND_REST_BASE_URL}/v1/invoice/{hash}"))
+            .header("Grpc-Metadata-macaroon", &macaroon_hex)
+            .send()
+            .await?;
+        if response.status() == reqwest::StatusCode::NOT_FOUND {
+            return Ok(false);
+        }
+        let body: serde_json::Value = response.error_for_status()?.json().await?;
+        let Some(price) = content_invoice_amount(&body, content_id) else {
+            return Ok(false);
+        };
+        if existing
+            .as_ref()
+            .is_some_and(|(_, expected)| *expected != price)
+        {
+            return Ok(false);
+        }
+        crate::content_invoice::record_pending(&self.config.data_dir, &hash, content_id, price)
+            .await?;
+        let settled = content_invoice_fully_settled(&body, price);
+        if settled {
+            crate::content_invoice::mark_paid(&self.config.data_dir, &hash).await?;
+        }
+        Ok(settled)
+    }
+
     /// Generate a fresh on-chain receive address (seller side, #46).
     pub(crate) async fn new_onchain_address(&self) -> Result<String> {
         let (client, macaroon_hex) = self.lnd_client().await?;
@@ -491,50 +569,15 @@ impl RpcHandler {
             .send()
             .await
             .context("Failed to list transactions")?;
-        if !resp.status().is_success() {
-            return Ok(false);
-        }
+        anyhow::ensure!(
+            resp.status().is_success(),
+            "Wallet transaction verification is unavailable"
+        );
         let body: serde_json::Value = resp
             .json()
             .await
             .context("Failed to parse transactions response")?;
-        let i64_field = |tx: &serde_json::Value, k: &str| -> i64 {
-            tx.get(k)
-                .and_then(|v| v.as_str())
-                .and_then(|s| s.parse::<i64>().ok())
-                .or_else(|| tx.get(k).and_then(|v| v.as_i64()))
-                .unwrap_or(0)
-        };
-        let txs = body
-            .get("transactions")
-            .and_then(|v| v.as_array())
-            .cloned()
-            .unwrap_or_default();
-        for tx in &txs {
-            if i64_field(tx, "num_confirmations") < 1 {
-                continue;
-            }
-            if i64_field(tx, "amount") < min_sats as i64 {
-                continue;
-            }
-            let pays_addr = tx
-                .get("dest_addresses")
-                .and_then(|v| v.as_array())
-                .map(|arr| arr.iter().any(|a| a.as_str() == Some(address)))
-                .unwrap_or(false)
-                || tx
-                    .get("output_details")
-                    .and_then(|v| v.as_array())
-                    .map(|arr| {
-                        arr.iter()
-                            .any(|o| o.get("address").and_then(|a| a.as_str()) == Some(address))
-                    })
-                    .unwrap_or(false);
-            if pays_addr {
-                return Ok(true);
-            }
-        }
-        Ok(false)
+        Ok(confirmed_address_sats(&body, address)? >= min_sats)
     }
 
     pub(in crate::api::rpc) async fn handle_lnd_createinvoice(
@@ -732,10 +775,24 @@ impl RpcHandler {
             total_amount += amount;
         }
 
-        let sat_per_vbyte = params
-            .get("fee_rate_sat_per_vbyte")
-            .and_then(|v| v.as_u64())
-            .unwrap_or(10);
+        let (_, explicit_rate) = super::fee_policy::fee_options(&serde_json::json!({
+            "sat_per_vbyte": params.get("fee_rate_sat_per_vbyte")
+        }))?;
+        let (client, macaroon_hex) = self.lnd_client().await?;
+        let sat_per_vbyte = if let Some(rate) = explicit_rate {
+            rate as u64
+        } else {
+            let response = client
+                .get(format!("{LND_REST_BASE_URL}/v2/wallet/estimatefee/1"))
+                .header("Grpc-Metadata-macaroon", &macaroon_hex)
+                .send()
+                .await
+                .context("Cannot estimate the next-block fee")?
+                .error_for_status()
+                .context("Next-block fee estimate rejected")?;
+            let estimate: serde_json::Value = response.json().await?;
+            super::fee_policy::estimated_sat_per_vbyte(&estimate)?
+        };
 
         info!(
             total_amount = total_amount,
@@ -743,8 +800,6 @@ impl RpcHandler {
             "Creating PSBT for hardware wallet signing"
         );
 
-        let (client, macaroon_hex) = self.lnd_client().await?;
-
         let fund_body = serde_json::json!({
             "raw": {
                 "outputs": lnd_outputs,
@@ -1289,10 +1344,207 @@ fn psbt_key_origin_report(psbt_base64: &str) -> Result<PsbtKeyOriginReport> {
     })
 }
 
+/// LND's transaction `amount` is the wallet-wide net amount, not the value
+/// paid to a purchase address. Attribute only confirmed output values, once
+/// per outpoint. Missing/malformed evidence is unknown, never proof of payment.
+pub(super) fn confirmed_address_sats(body: &serde_json::Value, address: &str) -> Result<u64> {
+    use std::collections::{HashMap, HashSet};
+    const MAX_SATS: u64 = 21_000_000 * 100_000_000;
+    fn integer(value: &serde_json::Value) -> Result<u64> {
+        match value {
+            serde_json::Value::String(s)
+                if !s.is_empty() && s.bytes().all(|c| c.is_ascii_digit()) =>
+            {
+                s.parse().context("Invalid on-chain output integer")
+            }
+            value => value
+                .as_u64()
+                .context("Missing or invalid on-chain output integer"),
+        }
+    }
+    anyhow::ensure!(!address.is_empty(), "Missing purchase address");
+    let transactions = body
+        .get("transactions")
+        .and_then(|v| v.as_array())
+        .context("Wallet omitted transaction evidence")?;
+    let mut seen = HashMap::new();
+    let mut total = 0u64;
+    for tx in transactions {
+        let confirmations = match &tx["num_confirmations"] {
+            serde_json::Value::String(s) => {
+                s.parse::<i64>().context("Invalid confirmation count")?
+            }
+            value => value.as_i64().context("Missing confirmation count")?,
+        };
+        if confirmations < 1 {
+            continue;
+        }
+        let hash = tx["tx_hash"]
+            .as_str()
+            .context("Missing transaction identifier")?;
+        anyhow::ensure!(
+            hash.len() == 64 && hash.bytes().all(|c| c.is_ascii_hexdigit()),
+            "Invalid transaction identifier"
+        );
+        if let Some(previous) = seen.insert(hash.to_ascii_lowercase(), tx) {
+            anyhow::ensure!(previous == tx, "Conflicting duplicate transaction evidence");
+            continue;
+        }
+        let outputs = tx["output_details"]
+            .as_array()
+            .context("Wallet omitted output values")?;
+        let mut indices = HashSet::new();
+        for output in outputs {
+            let index =
+                u32::try_from(integer(&output["output_index"])?).context("Invalid output index")?;
+            anyhow::ensure!(indices.insert(index), "Duplicate transaction output");
+            let amount = integer(&output["amount"])?;
+            anyhow::ensure!(amount <= MAX_SATS, "Invalid output amount");
+            // A non-address script (e.g. OP_RETURN) has no receiving address.
+            if output["address"].as_str() != Some(address) {
+                continue;
+            }
+            total = total
+                .checked_add(amount)
+                .filter(|sum| *sum <= MAX_SATS)
+                .context("Invalid total received amount")?;
+        }
+    }
+    Ok(total)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    fn payment_tx(hash: &str, confirmations: i64, outputs: serde_json::Value) -> serde_json::Value {
+        serde_json::json!({"tx_hash":hash.repeat(64),"num_confirmations":confirmations,
+            "amount":"999999","dest_addresses":["purchase"],"output_details":outputs})
+    }
+
+    #[test]
+    fn onchain_purchase_counts_only_its_outputs_not_wallet_total() {
+        let tx = payment_tx(
+            "a",
+            1,
+            serde_json::json!([
+                {"output_index":"0","amount":"1","address":"purchase"},
+                {"output_index":"1","amount":"999998","address":"other"}
+            ]),
+        );
+        assert_eq!(
+            confirmed_address_sats(&serde_json::json!({"transactions":[tx]}), "purchase").unwrap(),
+            1
+        );
+    }
+
+    #[test]
+    fn onchain_purchase_sums_confirmed_partial_outputs_once() {
+        let mut first = payment_tx(
+            "a",
+            1,
+            serde_json::json!([
+                {"output_index":0,"amount":"300","address":"purchase"},
+                {"output_index":"1","amount":46,"address":"purchase"}
+            ]),
+        );
+        first["amount"] = serde_json::json!("-9999"); // net wallet debit is irrelevant
+        let second = payment_tx(
+            "b",
+            2,
+            serde_json::json!([
+                {"output_index":"2","amount":"200","address":"purchase"}
+            ]),
+        );
+        let unconfirmed = payment_tx(
+            "c",
+            0,
+            serde_json::json!([
+                {"output_index":0,"amount":"10000","address":"purchase"}
+            ]),
+        );
+        let conflicted = payment_tx(
+            "d",
+            -1,
+            serde_json::json!([
+                {"output_index":0,"amount":"10000","address":"purchase"}
+            ]),
+        );
+        assert_eq!(confirmed_address_sats(&serde_json::json!({"transactions":[first.clone(),first,second,unconfirmed,conflicted]}), "purchase").unwrap(), 546);
+    }
+
+    #[test]
+    fn onchain_purchase_rejects_missing_values_and_ambiguous_outpoints() {
+        let good = payment_tx(
+            "a",
+            1,
+            serde_json::json!([
+                {"output_index":"0","amount":"546","address":"purchase"}
+            ]),
+        );
+        let mut no_values = good.clone();
+        no_values.as_object_mut().unwrap().remove("output_details");
+        let mut duplicate = good.clone();
+        duplicate["output_details"] = serde_json::json!([
+            {"output_index":0,"amount":300,"address":"purchase"},
+            {"output_index":0,"amount":300,"address":"purchase"}
+        ]);
+        let mut conflicting = good.clone();
+        conflicting["output_details"][0]["amount"] = serde_json::json!(1000);
+        for body in [
+            serde_json::json!({}),
+            serde_json::json!({"transactions":[no_values]}),
+            serde_json::json!({"transactions":[duplicate]}),
+            serde_json::json!({"transactions":[good.clone(),conflicting]}),
+        ] {
+            assert!(confirmed_address_sats(&body, "purchase").is_err());
+        }
+        for amount in [
+            serde_json::json!(-1),
+            serde_json::json!("0.00000546"),
+            serde_json::json!(546.5),
+            serde_json::json!(null),
+            serde_json::json!("18446744073709551616"),
+            serde_json::json!("2100000000000001"),
+        ] {
+            let mut invalid = good.clone();
+            invalid["output_details"][0]["amount"] = amount;
+            assert!(confirmed_address_sats(
+                &serde_json::json!({"transactions":[invalid]}),
+                "purchase"
+            )
+            .is_err());
+        }
+    }
+
+    #[test]
+    fn onchain_purchase_has_no_rounding_or_accumulation_overflow() {
+        let max = "2100000000000000";
+        let first = payment_tx(
+            "a",
+            1,
+            serde_json::json!([{"output_index":0,"amount":max,"address":"purchase"}]),
+        );
+        assert_eq!(
+            confirmed_address_sats(
+                &serde_json::json!({"transactions":[first.clone()]}),
+                "purchase"
+            )
+            .unwrap(),
+            2_100_000_000_000_000
+        );
+        let second = payment_tx(
+            "b",
+            1,
+            serde_json::json!([{"output_index":0,"amount":"1","address":"purchase"}]),
+        );
+        assert!(confirmed_address_sats(
+            &serde_json::json!({"transactions":[first,second]}),
+            "purchase"
+        )
+        .is_err());
+    }
+
     /// Build a minimal, genuinely unsigned one-input PSBT with no key origin on
     /// any input. Built programmatically rather than pasted as opaque base64 so
     /// the fixture states what it is.
@@ -1444,3 +1696,155 @@ mod tests {
         assert!(s.contains("[LND_REST_UNREACHABLE]"), "got: {s}");
     }
 }
+
+// LND REST uses decimal strings for int64 fields. Match the complete seller
+// memo, not a substring supplied by a buyer or an arbitrary settled invoice.
+fn json_u64(value: &serde_json::Value) -> Option<u64> {
+    value.as_u64().or_else(|| value.as_str()?.parse().ok())
+}
+fn content_invoice_fully_settled(body: &serde_json::Value, price: u64) -> bool {
+    let settled = match body.get("state").and_then(|v| v.as_str()) {
+        Some(state) => state == "SETTLED",
+        None => body.get("settled").and_then(|v| v.as_bool()) == Some(true),
+    };
+    settled
+        && price > 0
+        && body
+            .get("amt_paid_sat")
+            .and_then(json_u64)
+            .is_some_and(|paid| paid >= price)
+}
+fn content_invoice_amount(body: &serde_json::Value, content_id: &str) -> Option<u64> {
+    if body.get("memo")?.as_str()? != format!("Archipelago peer file {content_id}") {
+        return None;
+    }
+    body.get("value").and_then(json_u64).filter(|v| *v > 0)
+}
+
+#[cfg(test)]
+mod peer_file_invoice_tests {
+    use super::*;
+    #[test]
+    fn settlement_requires_terminal_state_and_full_amount() {
+        for state in ["OPEN", "ACCEPTED", "CANCELED", "unknown"] {
+            assert!(!content_invoice_fully_settled(
+                &serde_json::json!({"state":state,"settled":true,"amt_paid_sat":"100"}),
+                7
+            ));
+        }
+        for amount in [
+            serde_json::json!(6),
+            serde_json::json!("-1"),
+            serde_json::json!(null),
+            serde_json::json!("bad"),
+        ] {
+            assert!(!content_invoice_fully_settled(
+                &serde_json::json!({"state":"SETTLED","amt_paid_sat":amount}),
+                7
+            ));
+        }
+        for amount in [serde_json::json!(7), serde_json::json!("8")] {
+            assert!(content_invoice_fully_settled(
+                &serde_json::json!({"state":"SETTLED","amt_paid_sat":amount}),
+                7
+            ));
+        }
+        assert!(content_invoice_fully_settled(
+            &serde_json::json!({"settled":true,"amt_paid_sat":"7"}),
+            7
+        ));
+        assert!(!content_invoice_fully_settled(
+            &serde_json::json!({"state":"SETTLED","amt_paid_sat":"7"}),
+            0
+        ));
+    }
+    #[test]
+    fn legacy_recovery_requires_exact_file_memo_and_positive_amount() {
+        let invoice = serde_json::json!({"memo":"Archipelago peer file file-1", "value":"7"});
+        assert_eq!(content_invoice_amount(&invoice, "file-1"), Some(7));
+        assert_eq!(content_invoice_amount(&invoice, "file-2"), None);
+        for value in [
+            serde_json::json!("-1"),
+            serde_json::json!(0),
+            serde_json::json!("bad"),
+        ] {
+            let mut invalid = invoice.clone();
+            invalid["value"] = value;
+            assert_eq!(content_invoice_amount(&invalid, "file-1"), None);
+        }
+    }
+}
+
+fn content_invoice_lifecycle_body(body: &serde_json::Value, price: u64) -> serde_json::Value {
+    let settled = content_invoice_fully_settled(body, price);
+    let cancelled = !settled
+        && body["state"] == "CANCELED"
+        && body.get("settled").and_then(|value| value.as_bool()) != Some(true)
+        && body.get("amt_paid_sat").and_then(json_u64) == Some(0)
+        && body
+            .get("amt_paid_msat")
+            .is_none_or(|value| json_u64(value) == Some(0));
+    let state = if settled {
+        "settled"
+    } else if cancelled {
+        "canceled"
+    } else {
+        match body.get("state").and_then(|value| value.as_str()) {
+            Some("OPEN") => "open",
+            Some("ACCEPTED") => "accepted",
+            _ => "unknown",
+        }
+    };
+    let expires_at = body
+        .get("creation_date")
+        .and_then(json_u64)
+        .zip(body.get("expiry").and_then(json_u64))
+        .and_then(|(created, expiry)| created.checked_add(expiry));
+    // Expiry is informational. Only LND's terminal canceled state releases the
+    // cross-method block; wall-clock passage or lookup failure never does.
+    serde_json::json!({"paid":settled,"state":state,"can_switch_method":cancelled,
+        "expires_at":expires_at,"cancel_supported":false})
+}
+
+#[cfg(test)]
+mod invoice_lifecycle_tests {
+    use super::*;
+    #[test]
+    fn only_authoritative_zero_paid_cancel_unlocks_and_settlement_survives_expiry() {
+        for state in ["OPEN", "ACCEPTED", "UNKNOWN", "CANCELED"] {
+            for paid in [0u64, 1] {
+                let result = content_invoice_lifecycle_body(
+                    &serde_json::json!({
+                    "state":state,"settled":false,"amt_paid_sat":paid.to_string(),
+                    "creation_date":"1","expiry":"1"}),
+                    8,
+                );
+                assert_eq!(
+                    result["can_switch_method"],
+                    state == "CANCELED" && paid == 0
+                );
+                assert_eq!(result["paid"], false);
+            }
+        }
+        assert_eq!(
+            content_invoice_lifecycle_body(&serde_json::json!({"state":"CANCELED"}), 8)
+                ["can_switch_method"],
+            false
+        );
+        assert_eq!(
+            content_invoice_lifecycle_body(
+                &serde_json::json!({"state":"CANCELED", "amt_paid_sat":"0", "amt_paid_msat":"1"}),
+                8
+            )["can_switch_method"],
+            false
+        );
+        let paid = content_invoice_lifecycle_body(
+            &serde_json::json!({
+            "state":"SETTLED","settled":true,"amt_paid_sat":"8","value":"8",
+            "creation_date":"1","expiry":"1"}),
+            8,
+        );
+        assert_eq!(paid["paid"], true);
+        assert_eq!(paid["can_switch_method"], false);
+    }
+}

core/archipelago/src/api/rpc/media_registration.rs

@@ -0,0 +1,353 @@
+//! Owner-session/CSRF RPC plus producer-signed, exact media approval.
+//! App callers use the native dashboard bridge; this is never an origin-only grant.
+use super::RpcHandler;
+use crate::media_registration::{AuthorizedSelection, Intent, Limits};
+use anyhow::{Context, Result};
+use nostr_sdk::prelude::{Event, Kind};
+use serde::Deserialize;
+use std::{
+    path::Path,
+    sync::{
+        atomic::{AtomicBool, Ordering},
+        Arc,
+    },
+};
+
+// Dropping the request future cancels queued locks and chunked snapshot work.
+// A completed durable record is still recovered by the original operation ID.
+struct RequestCancellation(Arc<AtomicBool>);
+impl Drop for RequestCancellation {
+    fn drop(&mut self) {
+        self.0.store(true, Ordering::Relaxed);
+    }
+}
+fn request_cancellation() -> (RequestCancellation, Arc<AtomicBool>) {
+    let signal = Arc::new(AtomicBool::new(false));
+    (RequestCancellation(signal.clone()), signal)
+}
+
+const DOMAIN: &str = "archipelago.media-registration.approval.v1";
+const KIND: u16 = 27236;
+const MAX_APPROVAL: usize = 32 * 1024;
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct Params {
+    intent: Intent,
+    selection: AuthorizedSelection,
+    producer_event: Event,
+}
+
+const RESOLUTION_DOMAIN: &str = "archipelago.media-registration.resolution.v1";
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct ResolveParams {
+    intent: Intent,
+    producer_event: Event,
+}
+fn verified_resolution(input: serde_json::Value, now: u64) -> Result<ResolveParams> {
+    anyhow::ensure!(
+        serde_json::to_vec(&input)?.len() <= MAX_APPROVAL,
+        "Resolution approval is too large"
+    );
+    let params: ResolveParams = serde_json::from_value(input)?;
+    let event = &params.producer_event;
+    event
+        .verify()
+        .context("Resolution producer signature failed")?;
+    anyhow::ensure!(
+        event.kind == Kind::Custom(27237) && event.pubkey.to_hex() == params.intent.producer,
+        "Resolution signature purpose or producer changed"
+    );
+    let encoded = serde_json::to_value(event)?;
+    anyhow::ensure!(
+        encoded["tags"] == serde_json::json!([["d", RESOLUTION_DOMAIN]])
+            && event.created_at.as_u64() >= params.intent.created_at.saturating_sub(30)
+            && event.created_at.as_u64() <= now.saturating_add(30),
+        "Invalid resolution signature time or scope"
+    );
+    let content: serde_json::Value = serde_json::from_str(&event.content)?;
+    anyhow::ensure!(
+        content
+            == serde_json::json!({
+                "action":"Recover prepared video or retire this expired incomplete registration",
+                "scope":RESOLUTION_DOMAIN, "intent":params.intent,
+            }),
+        "Resolution signature changed the original intent"
+    );
+    Ok(params)
+}
+
+fn approval_content(intent: &Intent, selection: &AuthorizedSelection) -> Result<serde_json::Value> {
+    let path = selection
+        .relative_path
+        .to_str()
+        .context("Cloud file name is not UTF-8")?;
+    Ok(serde_json::json!({
+        "action":"Register this Cloud video for an IndeeHub project",
+        "scope":DOMAIN,
+        "intent":intent,
+        "selection":{"cloudFile":path,"paymentMethods":selection.payment_methods},
+    }))
+}
+fn verified_producer(params: &Params, now: u64) -> Result<String> {
+    let event = &params.producer_event;
+    anyhow::ensure!(
+        event.kind == Kind::Custom(KIND),
+        "This signature is not a media registration approval"
+    );
+    event
+        .verify()
+        .context("Producer approval signature failed")?;
+    let producer = event.pubkey.to_hex();
+    anyhow::ensure!(
+        producer == params.intent.producer,
+        "The signing identity differs from the project producer"
+    );
+    let created = event.created_at.as_u64();
+    anyhow::ensure!(
+        created >= params.intent.created_at.saturating_sub(30)
+            && created < params.intent.expires_at
+            && created <= now.saturating_add(30),
+        "Producer approval was not signed within this registration intent"
+    );
+    let encoded = serde_json::to_value(event)?;
+    anyhow::ensure!(
+        encoded["tags"] == serde_json::json!([["d", DOMAIN]]),
+        "Media approval signature scope changed"
+    );
+    let content: serde_json::Value = serde_json::from_str(&event.content)
+        .context("Producer approval is not readable registration terms")?;
+    anyhow::ensure!(
+        content == approval_content(&params.intent, &params.selection)?,
+        "Approved project, Cloud selection or rental terms changed"
+    );
+    Ok(producer)
+}
+fn parse(input: serde_json::Value, now: u64) -> Result<(Params, String)> {
+    anyhow::ensure!(
+        serde_json::to_vec(&input)?.len() <= MAX_APPROVAL,
+        "Registration approval is too large"
+    );
+    let params: Params = serde_json::from_value(input).context("Invalid registration approval")?;
+    let producer = verified_producer(&params, now)?;
+    Ok((params, producer))
+}
+fn registration_limit(_data_dir: &Path) -> u64 {
+    // Explicit per-file staging bound; shared immutable snapshot storage handles
+    // disk reservations separately before this route is enabled for live apps.
+    16 * 1024 * 1024 * 1024
+}
+impl RpcHandler {
+    /// Read-only public installation bindings for the native consent bridge.
+    /// A hidden standalone signer must compare its actual app origin with these
+    /// installed addresses; a caller-supplied app name is never sufficient.
+    pub(super) async fn handle_media_registration_context(
+        &self,
+        _input: serde_json::Value,
+    ) -> Result<serde_json::Value> {
+        let (state, _) = self.state_manager.get_snapshot().await;
+        let identity =
+            crate::identity::NodeIdentity::load_existing(&self.config.data_dir.join("identity"))
+                .await?;
+        let data_dir = self.config.data_dir.clone();
+        let context = tokio::task::spawn_blocking(move || {
+            crate::container::registration_pin::installed_context(&data_dir, &identity, &state)
+        })
+        .await??;
+        let mut result = serde_json::to_value(context)?;
+        result["paymentMethods"] = serde_json::json!(["cashu"]);
+        Ok(result)
+    }
+
+    pub(super) async fn handle_media_registration_resolve(
+        &self,
+        input: serde_json::Value,
+    ) -> Result<serde_json::Value> {
+        let now = u64::try_from(chrono::Utc::now().timestamp()).context("Invalid node clock")?;
+        let params = verified_resolution(input, now)?;
+        let (state, _) = self.state_manager.get_snapshot().await;
+        let identity =
+            crate::identity::NodeIdentity::load_existing(&self.config.data_dir.join("identity"))
+                .await?;
+        let data_dir = self.config.data_dir.clone();
+        let (_cancellation, cancelled) = request_cancellation();
+        tokio::task::spawn_blocking(move || {
+            crate::container::registration_pin::installed_context(&data_dir, &identity, &state)?;
+            crate::registered_media::resolve_registration(
+                &data_dir,
+                &identity,
+                &params.intent,
+                &params.producer_event.pubkey.to_hex(),
+                now,
+                &Limits {
+                    max_bytes: registration_limit(&data_dir),
+                    cancelled: &cancelled,
+                },
+            )
+        })
+        .await?
+    }
+
+    /// Standard RPC front door already requires owner session, permitted origin
+    /// and CSRF. Producer signature is additional exact-scope consent, not a
+    /// replacement for those owner checks. A replay repeats the original UUID.
+    pub(super) async fn handle_media_registration_prepare(
+        &self,
+        input: serde_json::Value,
+    ) -> Result<serde_json::Value> {
+        let now = u64::try_from(chrono::Utc::now().timestamp()).context("Invalid node clock")?;
+        let (params, producer) = parse(input, now)?;
+        let (state, _) = self.state_manager.get_snapshot().await;
+        anyhow::ensure!(
+            state
+                .package_data
+                .get("indeedhub-api")
+                .is_some_and(|entry| matches!(
+                    entry.state,
+                    crate::data_model::PackageState::Running
+                )),
+            "The installed IndeeHub API must be running to register its media"
+        );
+        let identity =
+            crate::identity::NodeIdentity::load_existing(&self.config.data_dir.join("identity"))
+                .await?;
+        let data_dir = self.config.data_dir.clone();
+        let (_cancellation, cancelled) = request_cancellation();
+        let receipt = tokio::task::spawn_blocking(move || {
+            crate::container::registration_pin::installed_context(&data_dir, &identity, &state)?;
+            let project = params.intent.project_id.clone();
+            let limits = Limits {
+                max_bytes: registration_limit(&data_dir),
+                cancelled: &cancelled,
+            };
+            crate::registered_media::register_approved_selection(
+                &data_dir,
+                &data_dir.join("filebrowser"),
+                &identity,
+                &crate::registered_media::ApprovedSelection {
+                    authenticated_producer: &producer,
+                    authenticated_project: &project,
+                    intent: &params.intent,
+                    selection: &params.selection,
+                },
+                now,
+                &limits,
+                |_| Ok(()),
+            )
+        })
+        .await??;
+        Ok(serde_json::to_value(receipt)?)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use nostr_sdk::prelude::{EventBuilder, Keys, Tag, Timestamp};
+    fn fixture() -> Params {
+        let keys = Keys::parse(&"07".repeat(32)).unwrap();
+        let intent = Intent {
+            version: 1,
+            request_id: uuid::Uuid::new_v4().to_string(),
+            nonce: "ab".repeat(32),
+            app_audience: uuid::Uuid::new_v4().to_string(),
+            node_did: crate::identity::did_key_from_pubkey_hex(&hex::encode([7; 32])).unwrap(),
+            producer: keys.public_key().to_hex(),
+            project_id: "fixture-project".into(),
+            price_sats: 8,
+            viewing_seconds: 3600,
+            created_at: 1000,
+            expires_at: 1600,
+        };
+        let selection = AuthorizedSelection {
+            relative_path: "Movies/Film.mp4".into(),
+            payment_methods: vec!["cashu".into()],
+        };
+        let event = EventBuilder::new(
+            Kind::Custom(KIND),
+            serde_json::to_string_pretty(&approval_content(&intent, &selection).unwrap()).unwrap(),
+        )
+        .tag(Tag::identifier(DOMAIN))
+        .custom_created_at(Timestamp::from(1200))
+        .sign_with_keys(&keys)
+        .unwrap();
+        Params {
+            intent,
+            selection,
+            producer_event: event,
+        }
+    }
+    #[test]
+    fn producer_signature_binds_human_readable_exact_selection_terms_node_and_installation() {
+        let original = fixture();
+        assert_eq!(
+            verified_producer(&original, 1300).unwrap(),
+            original.intent.producer
+        );
+        // Original consent can recover an already-completed operation after
+        // expiry; underlying snapshot journal refuses creating a fresh one.
+        assert!(verified_producer(&original, 2000).is_ok());
+        let mut changed = fixture();
+        changed.intent.price_sats += 1;
+        assert!(verified_producer(&changed, 1300).is_err());
+        let mut changed = fixture();
+        changed.selection.relative_path = "Other.mp4".into();
+        assert!(verified_producer(&changed, 1300).is_err());
+        let mut changed = fixture();
+        changed.intent.app_audience = uuid::Uuid::new_v4().to_string();
+        assert!(verified_producer(&changed, 1300).is_err());
+        let mut changed = fixture();
+        changed.intent.producer = "cd".repeat(32);
+        assert!(verified_producer(&changed, 1300).is_err());
+        assert!(verified_producer(&fixture(), 1000).is_err());
+    }
+    #[test]
+    fn request_parser_rejects_unsigned_claims_unknown_fields_and_changed_signed_content() {
+        let original = fixture();
+        let mut encoded = serde_json::json!({"intent":original.intent,"selection":original.selection,"producerEvent":original.producer_event});
+        assert!(parse(encoded.clone(), 1300).is_ok());
+        encoded["producerEvent"]["content"] = serde_json::json!("approve everything");
+        assert!(parse(encoded, 1300).is_err());
+        assert!(parse(serde_json::json!({"producer":"cd".repeat(32)}), 1300).is_err());
+    }
+    #[test]
+    fn dropped_request_signals_blocking_copy_cancellation() {
+        let (guard, signal) = request_cancellation();
+        assert!(!signal.load(Ordering::Relaxed));
+        drop(guard);
+        assert!(signal.load(Ordering::Relaxed));
+    }
+    #[test]
+    fn resolution_signature_recovers_only_exact_intent_after_expiry_without_file_authority() {
+        let original = fixture();
+        let keys = Keys::parse(&"07".repeat(32)).unwrap();
+        let event = EventBuilder::new(
+            Kind::Custom(27237),
+            serde_json::json!({
+                "action":"Recover prepared video or retire this expired incomplete registration",
+                "scope":RESOLUTION_DOMAIN,"intent":original.intent,
+            })
+            .to_string(),
+        )
+        .tag(Tag::identifier(RESOLUTION_DOMAIN))
+        .custom_created_at(Timestamp::from(1700))
+        .sign_with_keys(&keys)
+        .unwrap();
+        let encoded = serde_json::json!({"intent":original.intent,"producerEvent":event});
+        assert!(verified_resolution(encoded.clone(), 1800).is_ok());
+        assert!(verified_resolution(encoded.clone(), 9999).is_ok());
+        assert!(parse(encoded.clone(), 1800).is_err());
+        let mut changed = encoded.clone();
+        changed["intent"]["priceSats"] = serde_json::json!(999);
+        assert!(verified_resolution(changed, 1800).is_err());
+        let mut changed = encoded;
+        changed["selection"] =
+            serde_json::json!({"relative_path":"film.mp4","payment_methods":["cashu"]});
+        assert!(verified_resolution(changed, 1800).is_err());
+        assert!(verified_resolution(
+            serde_json::json!({"intent":original.intent,"producerEvent":original.producer_event}),
+            1800
+        )
+        .is_err());
+    }
+}

core/archipelago/src/api/rpc/mesh/messaging.rs

@@ -221,6 +221,10 @@ impl RpcHandler {
         params: Option<serde_json::Value>,
     ) -> Result<serde_json::Value> {
         let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        if let Some(job) = self.flash_job.read().await.as_ref() {
+            anyhow::ensure!(job.snapshot().await.done,
+                "A firmware flash is in progress; wait before reconnecting or changing radio settings");
+        }
 
         let mut config = mesh::load_config(&self.config.data_dir).await?;
 
@@ -325,7 +329,16 @@ impl RpcHandler {
         {
             let service_arc = Arc::clone(&self.mesh_service);
             let config_for_apply = config.clone();
+            let flash_jobs = Arc::clone(&self.flash_job);
             tokio::spawn(async move {
+                // Serialize against flash registration. If a flash started
+                // after this RPC saved settings, its completion applies them.
+                let flash_guard = flash_jobs.read().await;
+                if let Some(job) = flash_guard.as_ref() {
+                    if !job.snapshot().await.done {
+                        return;
+                    }
+                }
                 let mut service = service_arc.write().await;
                 if let Some(svc) = service.as_mut() {
                     if let Err(e) = svc.configure(config_for_apply).await {

core/archipelago/src/api/rpc/mesh/status.rs

@@ -110,7 +110,8 @@ impl RpcHandler {
         // `mesh.probe-device` call (e.g. the hot-swap modal's own re-probe)
         // from opening the identical port at the same time and corrupting
         // both operations' handshakes.
-        if let Some(job) = self.flash_job.read().await.as_ref() {
+        let flash_guard = self.flash_job.read().await;
+        if let Some(job) = flash_guard.as_ref() {
             anyhow::ensure!(
                 job.snapshot().await.done,
                 "A firmware flash is in progress — refusing to probe the serial port until it finishes"
@@ -131,6 +132,7 @@ impl RpcHandler {
             }
         }
         let probe = mesh::listener::probe_device(&path).await?;
+        drop(flash_guard);
         Ok(serde_json::to_value(probe)?)
     }
 

core/archipelago/src/api/rpc/middleware.rs

@@ -317,14 +317,14 @@ mod sanitize_tests {
 /// Deterministic: same session token always produces the same CSRF token.
 /// Survives backend restarts because it depends only on the session token
 /// and the on-disk remember secret (not ephemeral state).
-pub(crate) async fn derive_csrf_token(session_token: &str) -> String {
+pub(crate) async fn derive_csrf_token(session_token: &str) -> std::io::Result<String> {
     use hmac::{Hmac, Mac};
     use sha2::Sha256;
     type HmacSha256 = Hmac<Sha256>;
-    let secret = SessionStore::load_or_create_remember_secret().await;
+    let secret = SessionStore::load_or_create_remember_secret().await?;
     let mut mac = HmacSha256::new_from_slice(&secret).expect("HMAC key");
     mac.update(format!("csrf:{}", session_token).as_bytes());
-    hex::encode(mac.finalize().into_bytes())
+    Ok(hex::encode(mac.finalize().into_bytes()))
 }
 
 /// Extract a named cookie value from headers.

core/archipelago/src/api/rpc/mod.rs

@@ -17,8 +17,13 @@ mod fips;
 mod handshake;
 mod identity;
 mod interfaces;
+mod lightning_purchase;
+mod onchain_purchase;
 pub(crate) mod lnd;
 mod marketplace;
+mod media_registration;
+mod playback;
+mod purchase;
 // pub(crate): 13-10's `assistant::backends::select_backend` reuses
 // `mesh::assistant::detect_ollama()` (D-04) rather than re-probing —
 // matches the existing `pub(crate) mod bitcoin_relay;`/`pub(crate) mod
@@ -97,6 +102,40 @@ fn nostr_signing_origin_allowed(headers: &hyper::HeaderMap, dev_mode: bool) -> b
     matches!(url.port_or_known_default(), Some(80 | 443))
 }
 
+fn native_consent_origin_allowed(method: &str, headers: &hyper::HeaderMap, dev_mode: bool) -> bool {
+    !matches!(
+        method,
+        "node.nostr-sign"
+            | "identity.nostr-sign"
+            | "media.registration.prepare"
+            | "media.registration.context"
+            | "media.registration.resolve"
+            | "content.rental-purchase"
+
+            | "content.onchain-cancel"
+            | "content.onchain-attempt"
+            | "content.onchain-create"
+            | "content.onchain-expose"
+            | "content.onchain-prepare"
+            | "content.onchain-pay"
+            | "content.onchain-recover"
+            | "content.onchain-download"
+            | "content.invoice-pay"
+            | "content.invoice-download"
+            | "content.invoice-attempt"
+            | "content.invoice-retry-native"
+            | "content.invoice-create"
+            | "content.invoice-recover"
+            | "content.invoice-cancel"
+            | "content.purchase"
+            | "content.cancel-purchase"
+            | "content.playback-handle"
+            | "content.playback-status"
+            | "content.playback-prepare"
+            | "content.playback-start"
+    ) || nostr_signing_origin_allowed(headers, dev_mode)
+}
+
 /// Read-only authenticated methods may skip CSRF, but they must still exist in
 /// the dispatcher. The tab signer uses `system.get-hostname` as its lightweight
 /// session probe, so keeping the policy in one testable function protects that
@@ -148,6 +187,7 @@ pub struct RpcHandler {
     pub(crate) app_gate: Arc<crate::appgate::AppGate>,
     endpoint_rate_limiter: EndpointRateLimiter,
     response_cache: ResponseCache,
+    playback_handles: crate::playback_handles::PlaybackHandles,
     mesh_service: Arc<tokio::sync::RwLock<Option<crate::mesh::MeshService>>>,
     /// LoRa radio firmware-flash job state, sibling to `mesh_service` — one
     /// job at a time, since flashing needs exclusive access to the port.
@@ -172,6 +212,10 @@ pub struct RpcHandler {
 }
 
 impl RpcHandler {
+    pub(crate) fn playback_handles(&self) -> &crate::playback_handles::PlaybackHandles {
+        &self.playback_handles
+    }
+
     pub async fn new(
         config: Config,
         state_manager: Arc<StateManager>,
@@ -231,6 +275,7 @@ impl RpcHandler {
             app_gate,
             endpoint_rate_limiter,
             response_cache: ResponseCache::new(5),
+            playback_handles: Default::default(),
             mesh_service: Arc::new(tokio::sync::RwLock::new(None)),
             flash_job: crate::mesh::flash::new_job_handle(),
             transport_router: Arc::new(tokio::sync::RwLock::new(None)),
@@ -333,20 +378,26 @@ impl RpcHandler {
 
         debug!("RPC method: {}", rpc_req.method);
 
-        if matches!(
-            rpc_req.method.as_str(),
-            "node.nostr-sign" | "identity.nostr-sign"
-        ) && !nostr_signing_origin_allowed(&parts.headers, self.config.dev_mode)
-        {
+        if !native_consent_origin_allowed(&rpc_req.method, &parts.headers, self.config.dev_mode) {
             return Ok(self.error_response(
                 403,
-                "Nostr signing from app origins requires the dashboard consent bridge",
+                "Native signing and Cloud registration from app origins require the dashboard consent bridge",
                 StatusCode::FORBIDDEN,
             ));
         }
 
         // Enforce authentication for non-allowlisted methods
         let is_unauthenticated = UNAUTHENTICATED_METHODS.contains(&rpc_req.method.as_str());
+        if !is_unauthenticated || rpc_req.method.starts_with("auth.") {
+            if let Err(error) = SessionStore::load_or_create_remember_secret().await {
+                tracing::error!(%error, "Persistent session signing key unavailable");
+                return Ok(self.error_response(
+                    503,
+                    "Sign-in temporarily unavailable. Check server session storage.",
+                    StatusCode::SERVICE_UNAVAILABLE,
+                ));
+            }
+        }
         let mut new_session_cookies: Option<(String, String)> = None;
         if !is_unauthenticated {
             let mut authenticated = match &session_token {
@@ -359,7 +410,7 @@ impl RpcHandler {
                 if let Some(remember) = extract_cookie(&parts.headers, "remember") {
                     if crate::session::SessionStore::validate_remember_token(&remember).await {
                         let new_token = self.session_store.create().await;
-                        let new_csrf = derive_csrf_token(&new_token).await;
+                        let new_csrf = derive_csrf_token(&new_token).await?;
                         tracing::info!("Auto-restored session from remember-me token");
                         new_session_cookies = Some((new_token, new_csrf));
                         authenticated = true;
@@ -407,7 +458,7 @@ impl RpcHandler {
                     use hmac::{Hmac, Mac};
                     use sha2::Sha256;
                     type HmacSha256 = Hmac<Sha256>;
-                    let secret = SessionStore::load_or_create_remember_secret().await;
+                    let secret = SessionStore::load_or_create_remember_secret().await?;
                     let mut mac = match HmacSha256::new_from_slice(&secret) {
                         Ok(m) => m,
                         Err(_) => {
@@ -424,29 +475,28 @@ impl RpcHandler {
             };
 
             if !csrf_valid {
-                // Debug: log expected vs received for diagnosis
-                if let (Some(token), Some(header)) = (&session_token, &csrf_header) {
-                    let expected = derive_csrf_token(token).await;
-                    tracing::warn!(
-                        method = %rpc_req.method,
-                        session_prefix = %&token[..8.min(token.len())],
-                        csrf_prefix = %&header[..8.min(header.len())],
-                        expected_prefix = %&expected[..8.min(expected.len())],
-                        "403 CSRF mismatch — session/csrf/expected prefixes shown"
-                    );
-                } else {
-                    tracing::warn!(
-                        method = %rpc_req.method,
-                        has_session = session_token.is_some(),
-                        has_header = csrf_header.is_some(),
-                        "403 CSRF validation failed — rejecting RPC call"
-                    );
-                }
-                return Ok(self.error_response(
+                tracing::warn!(method = %rpc_req.method, "CSRF mismatch; rejecting action and refreshing authenticated session token");
+                let mut response = self.error_response(
                     403,
                     "CSRF token missing or invalid",
                     StatusCode::FORBIDDEN,
-                ));
+                );
+                // Authentication and RBAC have already passed. Reject this
+                // request without dispatch, but refresh the deterministic CSRF
+                // cookie so the browser can retry normally after a key rotation
+                // or a stale companion cookie. Never return a token to an
+                // unauthenticated client or relax CSRF validation on retry.
+                if let Some(token) = &session_token {
+                    self.set_csrf_cookie(
+                        &mut response,
+                        &derive_csrf_token(token).await?,
+                        secure_suffix,
+                    );
+                }
+                response
+                    .headers_mut()
+                    .insert("Cache-Control", cookie_header("private, no-store"));
+                return Ok(response);
             }
         }
 
@@ -551,7 +601,7 @@ impl RpcHandler {
             client_ip,
             secure_suffix,
         )
-        .await;
+        .await?;
 
         Ok(response)
     }
@@ -603,7 +653,7 @@ impl RpcHandler {
         new_session_cookies: &Option<(String, String)>,
         client_ip: std::net::IpAddr,
         secure_suffix: &str,
-    ) {
+    ) -> Result<()> {
         // Track failed login attempts for rate limiting
         if method == "auth.login" && rpc_resp.error.is_some() {
             self.login_rate_limiter.record_failure(client_ip).await;
@@ -643,7 +693,7 @@ impl RpcHandler {
                 if let Ok(Some(totp_data)) = self.auth_manager.get_totp_data().await {
                     if let Ok(secret) = crate::totp::decrypt_secret(&totp_data, password) {
                         let token = self.session_store.create_pending(secret).await;
-                        let csrf_token = derive_csrf_token(&token).await;
+                        let csrf_token = derive_csrf_token(&token).await?;
                         self.set_session_cookie(response, &token, secure_suffix);
                         self.set_csrf_cookie(response, &csrf_token, secure_suffix);
                         let totp_body = serde_json::json!({
@@ -656,8 +706,8 @@ impl RpcHandler {
                 }
             } else {
                 let token = self.session_store.create().await;
-                let csrf_token = derive_csrf_token(&token).await;
-                let remember_token = self.session_store.create_remember_token().await;
+                let csrf_token = derive_csrf_token(&token).await?;
+                let remember_token = self.session_store.create_remember_token().await?;
                 self.set_session_cookie(response, &token, secure_suffix);
                 self.set_csrf_cookie(response, &csrf_token, secure_suffix);
                 self.set_remember_cookie(response, &remember_token, secure_suffix);
@@ -676,8 +726,8 @@ impl RpcHandler {
                 .map(|s| s.to_string());
 
             if let Some(new_token) = new_token_opt {
-                let csrf_token = derive_csrf_token(&new_token).await;
-                let remember_token = self.session_store.create_remember_token().await;
+                let csrf_token = derive_csrf_token(&new_token).await?;
+                let remember_token = self.session_store.create_remember_token().await?;
                 self.set_session_cookie(response, &new_token, secure_suffix);
                 self.set_csrf_cookie(response, &csrf_token, secure_suffix);
                 self.set_remember_cookie(response, &remember_token, secure_suffix);
@@ -696,7 +746,7 @@ impl RpcHandler {
         if method == "auth.changePassword" && rpc_resp.error.is_none() {
             if let Some(token) = session_token {
                 let new_token = self.session_store.rotate(token).await;
-                let csrf_token = derive_csrf_token(&new_token).await;
+                let csrf_token = derive_csrf_token(&new_token).await?;
                 self.set_session_cookie(response, &new_token, secure_suffix);
                 self.set_csrf_cookie(response, &csrf_token, secure_suffix);
             }
@@ -728,6 +778,7 @@ impl RpcHandler {
             self.set_session_cookie(response, new_session, secure_suffix);
             self.set_csrf_cookie(response, new_csrf, secure_suffix);
         }
+        Ok(())
     }
 
     fn set_session_cookie(
@@ -789,6 +840,43 @@ mod nostr_signing_origin_tests {
         headers
     }
 
+    #[test]
+    fn native_registration_and_purchase_use_dashboard_origin_and_keep_authentication_and_csrf() {
+        for method in [
+            "media.registration.prepare",
+            "media.registration.context",
+            "media.registration.resolve",
+            "content.rental-purchase",
+            "content.onchain-cancel",
+            "content.onchain-attempt",
+            "content.onchain-create",
+            "content.onchain-expose",
+            "content.onchain-prepare",
+            "content.onchain-pay",
+            "content.onchain-recover",
+            "content.onchain-download",
+            "content.purchase",
+            "content.cancel-purchase",
+            "content.playback-handle",
+            "content.playback-status",
+            "content.playback-prepare",
+            "content.playback-start",
+        ] {
+            assert!(!native_consent_origin_allowed(
+                method,
+                &headers(Some("http://node.local:7778")),
+                false
+            ));
+            assert!(native_consent_origin_allowed(
+                method,
+                &headers(Some("https://node.local")),
+                false
+            ));
+            assert!(!UNAUTHENTICATED_METHODS.contains(&method));
+            assert!(!csrf_exempt_method(method));
+        }
+    }
+
     #[test]
     fn signing_accepts_dashboard_and_authenticated_non_browser_clients() {
         assert!(nostr_signing_origin_allowed(&headers(None), false));
@@ -834,3 +922,92 @@ mod session_probe_contract_tests {
         assert!(!DISPATCHER.contains("\"system.get-version\" =>"));
     }
 }
+
+#[cfg(test)]
+mod csrf_recovery_tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn stale_csrf_is_refreshed_without_executing_action_or_authenticating_strangers() {
+        let dir = tempfile::tempdir().unwrap();
+        let mut config = crate::config::Config::default();
+        config.data_dir = dir.path().to_path_buf();
+        config.dev_mode = false;
+        let sessions =
+            crate::session::SessionStore::new_for_tests(dir.path().join("sessions.json"));
+        let token = sessions.create().await;
+        let handler = Arc::new(
+            RpcHandler::new(
+                config,
+                Arc::new(crate::state::StateManager::new()),
+                Arc::new(crate::monitoring::MetricsStore::new()),
+                sessions,
+                None,
+                None,
+            )
+            .await
+            .unwrap(),
+        );
+        let request = |session: &str, csrf: Option<&str>, secure: bool| {
+            let mut builder = Request::builder()
+                .method("POST")
+                .uri("/rpc/v1")
+                .header("Cookie", format!("session={session}"));
+            if let Some(csrf) = csrf {
+                builder = builder.header("X-CSRF-Token", csrf);
+            }
+            if secure {
+                builder = builder.header("X-Forwarded-Proto", "https");
+            }
+            builder.body(hyper::Body::from(serde_json::json!({
+                "jsonrpc":"2.0", "id":1, "method":"system.settings.set",
+                "params":{"key":"ai_provider", "value":"{\"provider\":\"local\",\"openai_model\":\"\"}"}
+            }).to_string())).unwrap()
+        };
+        let settings = dir.path().join("settings/model-provider.json");
+        for stale in [None, Some("stale-token"), Some("00")] {
+            let response = handler
+                .clone()
+                .handle(request(&token, stale, true))
+                .await
+                .unwrap();
+            assert_eq!(response.status(), StatusCode::FORBIDDEN);
+            assert!(!settings.exists(), "rejected action must not have run");
+            let cookies: Vec<_> = response
+                .headers()
+                .get_all("set-cookie")
+                .iter()
+                .map(|v| v.to_str().unwrap())
+                .collect();
+            assert_eq!(cookies.len(), 1);
+            let expected = derive_csrf_token(&token).await.unwrap();
+            assert_eq!(
+                cookies[0],
+                format!("csrf_token={expected}; SameSite=Lax; Path=/; Secure")
+            );
+            assert_eq!(response.headers()["cache-control"], "private, no-store");
+        }
+        let stranger = handler
+            .clone()
+            .handle(request("not-a-session", None, true))
+            .await
+            .unwrap();
+        assert_eq!(stranger.status(), StatusCode::UNAUTHORIZED);
+        assert!(!stranger.headers().contains_key("set-cookie"));
+        assert!(!settings.exists());
+        let valid = derive_csrf_token(&token).await.unwrap();
+        let response = handler
+            .handle(request(&token, Some(&valid), false))
+            .await
+            .unwrap();
+        assert_eq!(response.status(), StatusCode::OK);
+        let body: serde_json::Value =
+            serde_json::from_slice(&hyper::body::to_bytes(response.into_body()).await.unwrap())
+                .unwrap();
+        assert!(
+            body["error"].is_null(),
+            "valid retry must reach the handler"
+        );
+        assert!(settings.exists());
+    }
+}

core/archipelago/src/api/rpc/onchain_purchase.rs

@@ -0,0 +1,983 @@
+//! Owner-only original-operation on-chain flow. No generic sendcoins fallback.
+use super::RpcHandler;
+use crate::{
+    content_lightning::Binding,
+    content_onchain::{self as engine, Journal, Phase, Record},
+};
+use anyhow::{Context, Result};
+use serde::Deserialize;
+use serde_json::{json, Value};
+use sha2::{Digest, Sha256};
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Params {
+    onion: String,
+    content_id: String,
+    operation_id: Option<String>,
+    price_sats: Option<u64>,
+    max_fee_sats: Option<u64>,
+    sat_per_vbyte: Option<u64>,
+    template_sha256: Option<String>,
+    plan_sha256: Option<String>,
+}
+fn public(record: &Record) -> Result<Value> {
+    let fee = record
+        .template
+        .as_ref()
+        .map(|t| engine::validate_funded(record, t))
+        .transpose()?;
+    let template_sha256 = record
+        .template
+        .as_ref()
+        .map(|t| hex::encode(Sha256::digest(t.psbt_base64.as_bytes())));
+    Ok(
+        json!({"operation_id":record.binding.id,"price_sats":record.binding.price_sats,"phase":record.phase,
+        "network":record.network(),"external_exposure":record.externally_exposed,
+        "address":if record.externally_exposed {record.quote.as_ref().map(|q|q.address.as_str())}else{None},
+        "fee_sats":fee.or_else(|| record.plan.as_ref().map(|p|p.fee_sats)),
+        "max_fee_sats":record.policy.as_ref().map(|p|p.max_fee_sats).or_else(||record.plan.as_ref().map(|p|p.max_fee_sats)),
+        "template_sha256":template_sha256,"plan_sha256":record.plan.as_ref().map(|p|p.hash()).transpose()?,
+        "txid":record.signed.as_ref().map(|s|s.txid.as_str()),"paid":record.settled,
+        "change_allocation_ambiguous":matches!(record.change_address,Some(engine::ChangeAddress::Dispatched)),
+        "can_switch_method":record.retirement.is_some(),"retired_unallocated":record.retirement.is_some()}),
+    )
+}
+impl RpcHandler {
+    async fn request_onchain_allocation(
+        &self,
+        record: &Record,
+        fips: &str,
+    ) -> Result<crate::content_onchain_seller::Record> {
+        let operation = crate::api::handler::onchain_purchase::Operation {
+            binding: record.binding.clone(),
+            action: "allocate".into(),
+        };
+        let (mut response, _) = crate::fips::dial::PeerRequest::new(
+            Some(fips),
+            &record.seller_onion,
+            crate::api::handler::onchain_purchase::ROUTE,
+        )
+        .require_fips()
+        .single_delivery()
+        .timeout(std::time::Duration::from_secs(45))
+        .send_content_json(
+            &self.config.data_dir,
+            &record.binding.seller_did,
+            &operation,
+        )
+        .await
+        .context("Original seller allocation reply unavailable; recover the same operation")?;
+        anyhow::ensure!(
+            response.status().is_success(),
+            "Original seller allocation remains unresolved"
+        );
+        let mut bytes = Vec::new();
+        while let Some(chunk) = response.chunk().await? {
+            anyhow::ensure!(
+                bytes.len() + chunk.len() <= 16384,
+                "Seller response too large"
+            );
+            bytes.extend_from_slice(&chunk);
+        }
+        let saved: crate::content_onchain_seller::Record = serde_json::from_slice(&bytes)?;
+        anyhow::ensure!(
+            saved.binding == record.binding,
+            "Seller changed original purchase"
+        );
+        if let Some(offer) = &record.offer {
+            anyhow::ensure!(saved.offer()? == *offer, "Seller changed original offer");
+        }
+        Ok(saved)
+    }
+    pub(super) async fn ensure_onchain_allows_other_rail(
+        &self,
+        buyer: &str,
+        seller: &str,
+        content: &str,
+    ) -> Result<()> {
+        anyhow::ensure!(
+            Journal::find_for(&self.config.data_dir, buyer, seller, content)?.is_none(),
+            "An original on-chain purchase remains recoverable; do not pay again or switch methods"
+        );
+        Ok(())
+    }
+    pub(super) async fn handle_onchain_operation(
+        &self,
+        params: Option<Value>,
+        action: &str,
+    ) -> Result<Value> {
+        let params: Params = serde_json::from_value(params.context("Missing on-chain operation")?)?;
+        anyhow::ensure!(
+            !params.content_id.starts_with("registered_"),
+            "Registered rentals require their native purchase contract"
+        );
+        let peer =
+            crate::federation::load_unique_payment_peer(&self.config.data_dir, &params.onion)
+                .await?;
+        let buyer =
+            crate::identity::NodeIdentity::load_existing(&self.config.data_dir.join("identity"))
+                .await?
+                .did_key()?;
+        anyhow::ensure!(buyer != peer.did, "Cannot buy from this same node");
+        let _admission = crate::content_payment_admission::lock(
+            &self.config.data_dir,
+            &buyer,
+            &peer.did,
+            &params.content_id,
+        )
+        .await?;
+        let original = if let Some(id) = &params.operation_id {
+            let journal = Journal::open(&self.config.data_dir, id).await?;
+            let original = journal.load()?;
+            if let Some(record) = &original {
+                anyhow::ensure!(
+                    record.binding.buyer_did == buyer
+                        && record.binding.seller_did == peer.did
+                        && record.binding.content_id == params.content_id,
+                    "Original on-chain operation belongs to another purchase"
+                );
+            }
+            original
+        } else {
+            Journal::find_for(&self.config.data_dir, &buyer, &peer.did, &params.content_id)?
+        };
+        if action == "lookup" {
+            return Ok(json!({"attempt":original.as_ref().map(public).transpose()?}));
+        }
+        if let Some(id) = &params.operation_id {
+            anyhow::ensure!(
+                original.as_ref().is_some_and(|r| &r.binding.id == id),
+                "Original on-chain operation changed"
+            );
+        }
+        let mut record = if let Some(record) = original {
+            record
+        } else {
+            anyhow::ensure!(
+                matches!(action, "create" | "expose") && params.operation_id.is_none(),
+                "Recover original on-chain operation first"
+            );
+            self.ensure_invoice_allows_other_rail(&buyer, &peer.did, &params.content_id)
+                .await?;
+            let cashu = crate::content_purchase::Journal::open(&self.config.data_dir).await?;
+            anyhow::ensure!(
+                cashu
+                    .find_buyers(&buyer, &peer.did, &params.content_id)
+                    .await?
+                    .iter()
+                    .all(|r| r.phase == crate::content_purchase::BuyerPhase::Cancelled),
+                "Recover or cancel original Cashu purchase first"
+            );
+            Record::new(
+                Binding {
+                    id: uuid::Uuid::new_v4().to_string(),
+                    buyer_did: buyer,
+                    seller_did: peer.did.clone(),
+                    content_id: params.content_id.clone(),
+                    price_sats: params.price_sats.context("Expected price required")?,
+                },
+                params.onion.clone(),
+            )?
+        };
+        anyhow::ensure!(
+            record.seller_onion == params.onion
+                && params
+                    .price_sats
+                    .is_none_or(|p| p == record.binding.price_sats),
+            "Original payment address or price changed"
+        );
+        let journal = Journal::open(&self.config.data_dir, &record.binding.id).await?;
+        if journal.load()?.is_none() {
+            journal.save(&record)?;
+        }
+        if record.retirement.is_some() {
+            return public(&record);
+        }
+        if action == "cancel" {
+            anyhow::ensure!(params.operation_id.is_some() && record.can_retire_unallocated(),"An allocated or mutated on-chain purchase cannot be canceled; recover its original payment");
+        }
+        if matches!(action, "create" | "expose" | "prepare" | "pay") && !record.settled {
+            // Recheck while the same admission guard is held, including resumes
+            // from another window and records predating this owner flow.
+            self.ensure_invoice_allows_other_rail(
+                &record.binding.buyer_did,
+                &peer.did,
+                &params.content_id,
+            )
+            .await?;
+            let cashu = crate::content_purchase::Journal::open(&self.config.data_dir).await?;
+            anyhow::ensure!(
+                cashu
+                    .find_buyers(&record.binding.buyer_did, &peer.did, &params.content_id)
+                    .await?
+                    .iter()
+                    .all(|r| r.phase == crate::content_purchase::BuyerPhase::Cancelled),
+                "Another saved Cashu liability must be recovered before on-chain dispatch"
+            );
+        }
+        if action == "prepare" {
+            anyhow::ensure!(
+                params.operation_id.is_some(),
+                "Original operation ID required"
+            );
+            if record.template.is_none() && record.plan.is_none() {
+                let max_fee_sats = params
+                    .max_fee_sats
+                    .context("Explicit maximum fee required")?;
+                anyhow::ensure!(
+                    (1..=2_100_000_000_000_000).contains(&max_fee_sats),
+                    "Invalid maximum fee"
+                );
+                if let Some(rate) = params.sat_per_vbyte {
+                    anyhow::ensure!((1..=5000).contains(&rate), "Invalid fee rate");
+                }
+                let wallet = self.onchain_purchase_wallet().await?;
+                let change = wallet.prepare_change(&journal).await?;
+                record = wallet
+                    .prepare_plan(
+                        &journal,
+                        super::lnd::onchain_purchase::PlanRequest {
+                            change_address: change,
+                            max_fee_sats,
+                            sat_per_vbyte: params.sat_per_vbyte,
+                        },
+                    )
+                    .await?;
+            }
+            return public(&record);
+        }
+        if action == "pay" {
+            anyhow::ensure!(
+                params.operation_id.is_some(),
+                "Original operation ID required"
+            );
+            if record.settled {
+                return public(&record);
+            }
+            if let Some(plan) = &record.plan {
+                anyhow::ensure!(
+                    params.plan_sha256.as_deref() == Some(plan.hash()?.as_str()),
+                    "Confirm the original saved funding plan before payment"
+                );
+            } else {
+                let template = record
+                    .template
+                    .as_ref()
+                    .context("Review the original fee first")?;
+                anyhow::ensure!(
+                    params.template_sha256.as_deref()
+                        == Some(
+                            hex::encode(Sha256::digest(template.psbt_base64.as_bytes())).as_str()
+                        ),
+                    "Confirm the original saved transaction before payment"
+                );
+            }
+            let wallet = self.onchain_purchase_wallet().await?;
+            if record.plan.is_some() && record.quote.is_none() {
+                record = engine::lease_plan(&journal, &wallet).await?;
+                engine::mark_address_allocation(&journal, false)?;
+                let status = self
+                    .request_onchain_allocation(
+                        &record,
+                        peer.fips_npub
+                            .as_deref()
+                            .context("Seller has no authenticated mesh connection")?,
+                    )
+                    .await?;
+                let quote = status
+                    .quote()?
+                    .context("Original seller allocation is unresolved; recover this operation")?;
+                record = engine::accept_quote(&journal, quote)?;
+            }
+            if record.plan.is_some() && record.template.is_none() {
+                record = engine::bind_plan(&journal)?;
+            }
+            if matches!(
+                record.phase,
+                Phase::TemplatePrepared | Phase::LeaseDispatched
+            ) {
+                record = engine::drive(&journal, &wallet, engine::Action::Lease, None).await?;
+            }
+            if matches!(record.phase, Phase::Funded | Phase::SigningDispatched) {
+                record = engine::drive(&journal, &wallet, engine::Action::Sign, None).await?;
+            }
+            if matches!(
+                record.phase,
+                Phase::Signed | Phase::BroadcastDispatched | Phase::Published
+            ) {
+                record = engine::drive(&journal, &wallet, engine::Action::Publish, None).await?;
+            }
+            return public(&record);
+        }
+        anyhow::ensure!(
+            matches!(
+                action,
+                "create" | "status" | "expose" | "download" | "cancel"
+            ),
+            "Unsupported on-chain action"
+        );
+        let fips = peer
+            .fips_npub
+            .context("Seller has no authenticated mesh connection")?;
+        if action == "expose" && record.offer.is_some() && record.quote.is_none() {
+            engine::mark_address_allocation(&journal, true)?;
+            let status = self.request_onchain_allocation(&record, &fips).await?;
+            record = engine::accept_quote(
+                &journal,
+                status
+                    .quote()?
+                    .context("Original seller allocation is unresolved; recover this operation")?,
+            )?;
+        }
+        let remote_action = if action == "create" || action == "expose" && record.offer.is_none() {
+            "offer"
+        } else if action == "expose" {
+            "status"
+        } else {
+            action
+        };
+        let operation = crate::api::handler::onchain_purchase::Operation {
+            binding: record.binding.clone(),
+            action: remote_action.into(),
+        };
+        let route = crate::api::handler::onchain_purchase::ROUTE;
+        let remote = crate::fips::dial::PeerRequest::new(Some(&fips), &params.onion, route)
+            .require_fips()
+            .single_delivery()
+            .timeout(std::time::Duration::from_secs(if action == "download" {
+                900
+            } else {
+                45
+            }))
+            .send_content_json(&self.config.data_dir, &peer.did, &operation)
+            .await;
+        let (mut response, _) = match remote {
+            Ok(value) => value,
+            Err(_) => {
+                return Ok(
+                    json!({"attempt":public(&record)?,"recovery_required":true,"error":"Original on-chain request is saved. Recover this operation; do not request another address or pay again."}),
+                )
+            }
+        };
+        anyhow::ensure!(
+            response.status().is_success(),
+            "Seller could not recover original on-chain purchase {}; retain it",
+            record.binding.id
+        );
+        if action == "download" {
+            let source = record
+                .quote
+                .as_ref()
+                .context("Recover original address first")?
+                .source
+                .clone();
+            anyhow::ensure!(
+                response.content_length() == Some(source.size),
+                "Original file length changed"
+            );
+            record.settled = true;
+            journal.save(&record)?;
+            let stream = crate::content_purchase_download::verified_stream(
+                response.bytes_stream(),
+                source.sha256,
+                source.size,
+            );
+            let owned = crate::content_owned::record_purchase_stream(
+                &self.config.data_dir,
+                crate::content_owned::OwnedItem {
+                    onion: params.onion,
+                    content_id: params.content_id,
+                    filename: source.filename,
+                    mime_type: source.mime_type,
+                    size_bytes: source.size,
+                    paid_sats: record.binding.price_sats,
+                    ecash_backend: "onchain".into(),
+                    purchased_at: chrono::Utc::now().to_rfc3339(),
+                    download_complete: false,
+                },
+                Box::pin(stream),
+                Some(source.size),
+            )
+            .await?;
+            return Ok(
+                json!({"owned":true,"owned_content_id":owned.content_id,"mime_type":owned.mime_type}),
+            );
+        }
+        let mut bytes = vec![];
+        while let Some(chunk) = response.chunk().await? {
+            anyhow::ensure!(
+                bytes.len() + chunk.len() <= 16384,
+                "On-chain response too large"
+            );
+            bytes.extend_from_slice(&chunk);
+        }
+        let body: Value = serde_json::from_slice(&bytes)?;
+        if body["state"] == "cancelled_unallocated" {
+            let ack: crate::content_onchain_seller::UnallocatedAck = serde_json::from_value(body)?;
+            record = engine::retire_unallocated(&journal, ack)?;
+            return public(&record);
+        }
+        anyhow::ensure!(
+            action != "cancel",
+            "Seller did not acknowledge unallocated retirement; preserve original operation"
+        );
+        let status: crate::content_onchain_seller::Record = serde_json::from_value(body)?;
+        anyhow::ensure!(
+            status.binding == record.binding,
+            "Seller changed original purchase"
+        );
+        if record.offer.is_none() && record.quote.is_none() {
+            record = engine::accept_offer(&journal, status.offer()?)?;
+        }
+        if let Some(quote) = status.quote()? {
+            record = engine::accept_quote(&journal, quote)?;
+        }
+        anyhow::ensure!(
+            !status.paid || record.quote.is_some(),
+            "Paid purchase lacks original address"
+        );
+        record.settled |= status.paid;
+        journal.save(&record)?;
+        if action == "expose" && !record.settled {
+            if record.quote.is_none() {
+                engine::mark_address_allocation(&journal, true)?;
+                let status = self.request_onchain_allocation(&record, &fips).await?;
+                record = engine::accept_quote(
+                    &journal,
+                    status.quote()?.context(
+                        "Original seller allocation is unresolved; recover this operation",
+                    )?,
+                )?;
+            }
+            engine::expose_address(&journal)?;
+            record = journal.load()?.context("Original record unavailable")?;
+        }
+        public(&record)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    fn binding() -> Binding {
+        Binding {
+            id: uuid::Uuid::new_v4().to_string(),
+            buyer_did: crate::identity::did_key_from_pubkey_hex(&hex::encode([7; 32])).unwrap(),
+            seller_did: crate::identity::did_key_from_pubkey_hex(&hex::encode([8; 32])).unwrap(),
+            content_id: "file".into(),
+            price_sats: 546,
+        }
+    }
+    #[tokio::test]
+    async fn rental_preserves_unresolved_lightning_operation_on_review_and_delayed_consent() {
+        let data = tempfile::tempdir().unwrap();
+        let identity = crate::identity::NodeIdentity::load_or_create(&data.path().join("identity"))
+            .await
+            .unwrap();
+        let mut binding = binding();
+        binding.buyer_did = identity.did_key().unwrap();
+        binding.content_id = "registered_rental".into();
+        let onion = format!("{}.onion", "a".repeat(56));
+        let peer = serde_json::from_value(json!({
+            "did": binding.seller_did, "pubkey": hex::encode([8; 32]),
+            "onion": onion, "trust_level": "trusted", "added_at": "now",
+            "fips_npub": "fixture-no-network"
+        }))
+        .unwrap();
+        crate::federation::save_nodes(data.path(), &[peer])
+            .await
+            .unwrap();
+        let mut config = crate::config::Config::default();
+        config.data_dir = data.path().to_path_buf();
+        let handler = RpcHandler::new(
+            config,
+            std::sync::Arc::new(crate::state::StateManager::new()),
+            std::sync::Arc::new(crate::monitoring::MetricsStore::new()),
+            crate::session::SessionStore::new_for_tests(data.path().join("sessions.json")),
+            None,
+            None,
+        )
+        .await
+        .unwrap();
+        let journal = crate::content_lightning::Journal::open(data.path())
+            .await
+            .unwrap();
+        let record = crate::content_lightning::BuyerRecord {
+            binding: crate::content_lightning::Binding {
+                id: binding.id.clone(),
+                buyer_did: binding.buyer_did.clone(),
+                seller_did: binding.seller_did.clone(),
+                content_id: binding.content_id.clone(),
+                price_sats: 546,
+            },
+            seller_onion: onion,
+            external_exposure: true,
+            native_retired: false,
+            native_replacement: None,
+            native_dispatched: false,
+            native_result: None,
+            last: None,
+        };
+        journal.save_buyer(&record).unwrap();
+        drop(journal);
+        for consent in [
+            None,
+            Some(json!({
+                "operation_id": uuid::Uuid::new_v4().to_string(),
+                "envelope_sha256": "cd".repeat(32), "wallet_debit_sats": 546
+            })),
+        ] {
+            let error = handler
+                .handle_content_rental_purchase(Some(json!({
+                    "seller_did": binding.seller_did, "content_id": binding.content_id,
+                    "expected_sha256": "ab".repeat(32), "expected_price_sats": 546,
+                    "expected_viewing_seconds": 3600, "max_wallet_debit": 546, "consent": consent
+                })))
+                .await
+                .unwrap_err();
+            assert!(
+                error
+                    .to_string()
+                    .contains("externally payable invoice remains unresolved"),
+                "{error:#}"
+            );
+        }
+        let journal = crate::content_lightning::Journal::open(data.path())
+            .await
+            .unwrap();
+        assert_eq!(
+            serde_json::to_value(journal.buyer(&binding.id).unwrap().unwrap()).unwrap(),
+            serde_json::to_value(record).unwrap()
+        );
+        assert!(!data.path().join("wallet").exists());
+        assert!(crate::content_purchase::Journal::open(data.path())
+            .await
+            .unwrap()
+            .find_buyers(&binding.buyer_did, &binding.seller_did, &binding.content_id)
+            .await
+            .unwrap()
+            .is_empty());
+    }
+
+    #[tokio::test]
+    async fn rental_waits_for_alternate_rail_commit_and_rejects_quote_and_consent_recovery() {
+        let data = tempfile::tempdir().unwrap();
+        let identity = crate::identity::NodeIdentity::load_or_create(&data.path().join("identity"))
+            .await
+            .unwrap();
+        let mut binding = binding();
+        binding.buyer_did = identity.did_key().unwrap();
+        binding.content_id = "registered_rental".into();
+        let onion = format!("{}.onion", "a".repeat(56));
+        let peer = serde_json::from_value(json!({
+            "did": binding.seller_did, "pubkey": hex::encode([8; 32]),
+            "onion": onion, "trust_level": "trusted", "added_at": "now",
+            "fips_npub": "fixture-no-network"
+        }))
+        .unwrap();
+        crate::federation::save_nodes(data.path(), &[peer])
+            .await
+            .unwrap();
+        let mut config = crate::config::Config::default();
+        config.data_dir = data.path().to_path_buf();
+        let handler = RpcHandler::new(
+            config,
+            std::sync::Arc::new(crate::state::StateManager::new()),
+            std::sync::Arc::new(crate::monitoring::MetricsStore::new()),
+            crate::session::SessionStore::new_for_tests(data.path().join("sessions.json")),
+            None,
+            None,
+        )
+        .await
+        .unwrap();
+        // The other rail owns admission before it persists the uncertain spend.
+        let admission = crate::content_payment_admission::lock(
+            data.path(),
+            &binding.buyer_did,
+            &binding.seller_did,
+            &binding.content_id,
+        )
+        .await
+        .unwrap();
+        let params = json!({
+            "seller_did": binding.seller_did, "content_id": binding.content_id,
+            "expected_sha256": "ab".repeat(32), "expected_price_sats": 546,
+            "expected_viewing_seconds": 3600, "max_wallet_debit": 546
+        });
+        let pending = handler.handle_content_rental_purchase(Some(params.clone()));
+        tokio::pin!(pending);
+        assert!(
+            tokio::time::timeout(std::time::Duration::from_millis(50), &mut pending)
+                .await
+                .is_err(),
+            "Rental must wait for cross-rail admission before inspecting journals/context"
+        );
+        let journal = Journal::open(data.path(), &binding.id).await.unwrap();
+        journal
+            .save(&Record::new(binding.clone(), onion.clone()).unwrap())
+            .unwrap();
+        drop(journal);
+        let path = data
+            .path()
+            .join("content-onchain")
+            .join(format!("{}.json", binding.id));
+        let original = std::fs::read(&path).unwrap();
+        drop(admission);
+        let error = tokio::time::timeout(std::time::Duration::from_secs(5), &mut pending)
+            .await
+            .unwrap()
+            .unwrap_err();
+        assert!(
+            error.to_string().contains("original on-chain purchase"),
+            "{error:#}"
+        );
+        for consent in [
+            None,
+            Some(json!({
+                "operation_id": uuid::Uuid::new_v4().to_string(),
+                "envelope_sha256": "cd".repeat(32), "wallet_debit_sats": 546
+            })),
+        ] {
+            let mut retry = params.clone();
+            retry["consent"] = consent.unwrap_or(serde_json::Value::Null);
+            let error = handler
+                .handle_content_rental_purchase(Some(retry))
+                .await
+                .unwrap_err();
+            assert!(
+                error.to_string().contains("original on-chain purchase"),
+                "{error:#}"
+            );
+        }
+        assert_eq!(std::fs::read(path).unwrap(), original);
+        assert!(!data.path().join("wallet").exists());
+        assert!(crate::content_purchase::Journal::open(data.path())
+            .await
+            .unwrap()
+            .find_buyers(&binding.buyer_did, &binding.seller_did, &binding.content_id)
+            .await
+            .unwrap()
+            .is_empty());
+    }
+
+    #[tokio::test]
+    async fn unresolved_onchain_operation_blocks_cashu_and_every_lightning_spend_entry() {
+        let data = tempfile::tempdir().unwrap();
+        let identity = crate::identity::NodeIdentity::load_or_create(&data.path().join("identity"))
+            .await
+            .unwrap();
+        let mut binding = binding();
+        binding.buyer_did = identity.did_key().unwrap();
+        let onion = format!("{}.onion", "a".repeat(56));
+        let peer = serde_json::from_value(json!({
+            "did": binding.seller_did, "pubkey": hex::encode([8; 32]),
+            "onion": onion, "trust_level": "trusted", "added_at": "now",
+            "fips_npub": "fixture-no-network"
+        }))
+        .unwrap();
+        crate::federation::save_nodes(data.path(), &[peer])
+            .await
+            .unwrap();
+        let mut config = crate::config::Config::default();
+        config.data_dir = data.path().to_path_buf();
+        let handler = RpcHandler::new(
+            config,
+            std::sync::Arc::new(crate::state::StateManager::new()),
+            std::sync::Arc::new(crate::monitoring::MetricsStore::new()),
+            crate::session::SessionStore::new_for_tests(data.path().join("sessions.json")),
+            None,
+            None,
+        )
+        .await
+        .unwrap();
+        let journal = Journal::open(data.path(), &binding.id).await.unwrap();
+        journal
+            .save(&Record::new(binding.clone(), onion.clone()).unwrap())
+            .unwrap();
+        drop(journal);
+        let original = std::fs::read(
+            data.path()
+                .join("content-onchain")
+                .join(format!("{}.json", binding.id)),
+        )
+        .unwrap();
+
+        // Exercise the real RPC entry points, not just the admission helper.
+        // Each must reject before a Cashu/Lightning journal, offer, invoice or
+        // wallet dispatch is created, including delayed callbacks and retries.
+        for consent in [
+            None,
+            Some(json!({
+                "operation_id": uuid::Uuid::new_v4().to_string(),
+                "envelope_sha256": "ab".repeat(32), "wallet_debit_sats": 546
+            })),
+        ] {
+            let error = handler
+                .handle_content_purchase(Some(json!({
+                    "onion": onion, "content_id": binding.content_id,
+                    "max_wallet_debit": 546, "consent": consent
+                })))
+                .await
+                .unwrap_err();
+            assert!(
+                error.to_string().contains("original on-chain purchase"),
+                "{error:#}"
+            );
+        }
+        for (action, exposure) in [
+            ("create", false),
+            ("pay", false),
+            ("retry", false),
+            ("create", true),
+            ("status", true),
+        ] {
+            let error = handler
+                .handle_lightning_operation(
+                    Some(json!({
+                        "onion": onion, "content_id": binding.content_id,
+                        "price_sats": 546, "external_exposure": exposure
+                    })),
+                    action,
+                )
+                .await
+                .unwrap_err();
+            assert!(
+                error.to_string().contains("original on-chain purchase"),
+                "{action}: {error:#}"
+            );
+        }
+        // Read-only recovery lookup remains available despite the blocked rail.
+        let lookup = handler
+            .handle_lightning_operation(
+                Some(json!({
+                    "onion": onion, "content_id": binding.content_id
+                })),
+                "lookup",
+            )
+            .await
+            .unwrap();
+        assert!(lookup["attempt"].is_null());
+        assert_eq!(
+            std::fs::read(
+                data.path()
+                    .join("content-onchain")
+                    .join(format!("{}.json", binding.id))
+            )
+            .unwrap(),
+            original
+        );
+        assert!(!data.path().join("wallet").exists());
+        // No replacement operation has been persisted by any rejected call.
+        assert!(crate::content_purchase::Journal::open(data.path())
+            .await
+            .unwrap()
+            .find_buyers(&binding.buyer_did, &binding.seller_did, &binding.content_id)
+            .await
+            .unwrap()
+            .is_empty());
+        assert!(crate::content_lightning::Journal::open(data.path())
+            .await
+            .unwrap()
+            .buyer_for(&binding.buyer_did, &binding.seller_did, &binding.content_id)
+            .unwrap()
+            .is_none());
+    }
+
+    #[tokio::test]
+    async fn buyer_discovery_retains_unresolved_address_and_rejects_duplicate_operations() {
+        let data = tempfile::tempdir().unwrap();
+        let binding = binding();
+        let saved = Record::new(binding.clone(), format!("{}.onion", "a".repeat(56))).unwrap();
+        let j = Journal::open(data.path(), &binding.id).await.unwrap();
+        j.save(&saved).unwrap();
+        drop(j);
+        let found = Journal::find_for(
+            data.path(),
+            &binding.buyer_did,
+            &binding.seller_did,
+            &binding.content_id,
+        )
+        .unwrap()
+        .unwrap();
+        assert_eq!(found.binding.id, binding.id);
+        assert!(found.blocks_other_rails());
+        assert!(public(&found).unwrap()["address"].is_null());
+        assert!(Journal::find_for(
+            data.path(),
+            &binding.seller_did,
+            &binding.buyer_did,
+            &binding.content_id
+        )
+        .unwrap()
+        .is_none());
+        let mut second = binding.clone();
+        second.id = uuid::Uuid::new_v4().to_string();
+        let j = Journal::open(data.path(), &second.id).await.unwrap();
+        j.save(&Record::new(second, saved.seller_onion).unwrap())
+            .unwrap();
+        drop(j);
+        assert!(Journal::find_for(
+            data.path(),
+            &binding.buyer_did,
+            &binding.seller_did,
+            &binding.content_id
+        )
+        .is_err());
+    }
+    #[tokio::test]
+    async fn corrupted_node_record_cannot_be_treated_as_permission_to_pay_again() {
+        let data = tempfile::tempdir().unwrap();
+        let binding = binding();
+        let j = Journal::open(data.path(), &binding.id).await.unwrap();
+        j.save(&Record::new(binding.clone(), format!("{}.onion", "a".repeat(56))).unwrap())
+            .unwrap();
+        drop(j);
+        std::fs::write(
+            data.path()
+                .join("content-onchain")
+                .join(format!("{}.json", binding.id)),
+            b"{}",
+        )
+        .unwrap();
+        assert!(Journal::find_for(
+            data.path(),
+            &binding.buyer_did,
+            &binding.seller_did,
+            &binding.content_id
+        )
+        .is_err());
+    }
+    #[tokio::test]
+    async fn only_durable_matching_empty_ack_releases_cross_rail_and_stale_callback_cannot_revive()
+    {
+        let data = tempfile::tempdir().unwrap();
+        let binding = binding();
+        let _rail = crate::content_payment_admission::lock(
+            data.path(),
+            &binding.buyer_did,
+            &binding.seller_did,
+            &binding.content_id,
+        )
+        .await
+        .unwrap();
+        let journal = Journal::open(data.path(), &binding.id).await.unwrap();
+        let original = Record::new(binding.clone(), format!("{}.onion", "a".repeat(56))).unwrap();
+        journal.save(&original).unwrap();
+        let ack = crate::content_onchain_seller::UnallocatedAck {
+            binding: binding.clone(),
+            state: "cancelled_unallocated".into(),
+            address: serde_json::Value::Null,
+            allocation_dispatched: false,
+            can_switch_method: true,
+        };
+        for wrong in [
+            crate::content_onchain_seller::UnallocatedAck {
+                allocation_dispatched: true,
+                ..ack.clone()
+            },
+            crate::content_onchain_seller::UnallocatedAck {
+                address: serde_json::json!("not-empty"),
+                ..ack.clone()
+            },
+            crate::content_onchain_seller::UnallocatedAck {
+                binding: Binding {
+                    id: uuid::Uuid::new_v4().to_string(),
+                    ..binding.clone()
+                },
+                ..ack.clone()
+            },
+        ] {
+            assert!(engine::retire_unallocated(&journal, wrong).is_err());
+        }
+        assert!(Journal::find_for(
+            data.path(),
+            &binding.buyer_did,
+            &binding.seller_did,
+            &binding.content_id
+        )
+        .unwrap()
+        .is_some());
+        let retired = engine::retire_unallocated(&journal, ack).unwrap();
+        assert!(!retired.blocks_other_rails());
+        assert!(public(&retired).unwrap()["can_switch_method"] == true);
+        assert!(journal.save(&original).is_err());
+        drop(journal);
+        assert!(Journal::find_for(
+            data.path(),
+            &binding.buyer_did,
+            &binding.seller_did,
+            &binding.content_id
+        )
+        .unwrap()
+        .is_none());
+        let mut replacement = binding.clone();
+        replacement.id = uuid::Uuid::new_v4().to_string();
+        let journal = Journal::open(data.path(), &replacement.id).await.unwrap();
+        journal
+            .save(&Record::new(replacement.clone(), original.seller_onion).unwrap())
+            .unwrap();
+        drop(journal);
+        assert_eq!(
+            Journal::find_for(
+                data.path(),
+                &binding.buyer_did,
+                &binding.seller_did,
+                &binding.content_id
+            )
+            .unwrap()
+            .unwrap()
+            .binding
+            .id,
+            replacement.id
+        );
+    }
+    #[tokio::test]
+    async fn owner_address_is_redacted_until_exposure_is_durable_and_cannot_then_be_retired() {
+        let data = tempfile::tempdir().unwrap();
+        let binding = binding();
+        let journal = Journal::open(data.path(), &binding.id).await.unwrap();
+        journal
+            .save(&Record::new(binding.clone(), format!("{}.onion", "a".repeat(56))).unwrap())
+            .unwrap();
+        let mut bytes = vec![0, 20];
+        bytes.extend([1; 20]);
+        let address = bitcoin::Address::from_script(
+            &bitcoin::ScriptBuf::from_bytes(bytes),
+            bitcoin::Network::Regtest,
+        )
+        .unwrap()
+        .to_string();
+        let saved = engine::accept_quote(
+            &journal,
+            engine::Quote {
+                binding: binding.clone(),
+                address: address.clone(),
+                network: engine::ChainNetwork::Regtest,
+                source: crate::content_lightning::RetainedFile {
+                    sha256: "a".repeat(64),
+                    size: 4,
+                    filename: "original.txt".into(),
+                    mime_type: "text/plain".into(),
+                },
+            },
+        )
+        .unwrap();
+        assert!(public(&saved).unwrap()["address"].is_null());
+        let ack = crate::content_onchain_seller::UnallocatedAck {
+            binding: binding.clone(),
+            state: "cancelled_unallocated".into(),
+            address: serde_json::Value::Null,
+            allocation_dispatched: false,
+            can_switch_method: true,
+        };
+        assert!(engine::retire_unallocated(&journal, ack.clone()).is_err());
+        assert_eq!(engine::expose_address(&journal).unwrap(), address);
+        drop(journal);
+        let journal = Journal::open(data.path(), &binding.id).await.unwrap();
+        let exposed = journal.load().unwrap().unwrap();
+        assert!(exposed.externally_exposed);
+        assert_eq!(public(&exposed).unwrap()["address"], address);
+        assert!(engine::retire_unallocated(&journal, ack).is_err());
+        assert!(exposed.blocks_other_rails());
+    }
+}

core/archipelago/src/api/rpc/package/async_lifecycle.rs

@@ -89,6 +89,15 @@ impl RpcHandler {
             match handler.handle_package_install(params).await {
                 Ok(_) => {
                     info!("package.install {}: complete", package_id_spawn);
+                    for id in [&package_id_spawn, &format!("archy-{}", package_id_spawn)] {
+                        crate::crash_recovery::clear_user_uninstalled(&handler.config.data_dir, id)
+                            .await;
+                    }
+                    crate::crash_recovery::mark_installed(
+                        &handler.config.data_dir,
+                        &package_id_spawn,
+                    )
+                    .await;
                     // The install pipeline has verified the container is up
                     // and healthy (see install.rs post-start exit check).
                     // Kick the scanner first so the fresh manifest (with
@@ -184,7 +193,9 @@ impl RpcHandler {
                     // phase is cleared (None) so no stale InstallPhase
                     // lingers on the card.
                     let err_msg = format!("Install failed: {:#}", e);
-                    let (mut data, _) = handler.state_manager.get_snapshot().await;
+                    handler
+                        .state_manager
+                        .mutate_data(|data| {
                             if let Some(entry) = data.package_data.get_mut(&package_id_spawn) {
                                 entry.state = PackageState::Stopped;
                                 entry.install_progress = Some(crate::data_model::InstallProgress {
@@ -193,8 +204,9 @@ impl RpcHandler {
                                     phase: None,
                                     message: Some(err_msg),
                                 });
-                        handler.state_manager.update_data(data).await;
                             }
+                        })
+                        .await;
                 }
             }
         });
@@ -252,6 +264,11 @@ impl RpcHandler {
             match handler.handle_package_uninstall(params).await {
                 Ok(_) => {
                     info!("package.uninstall {}: complete", package_id_spawn);
+                    for id in [&package_id_spawn, &format!("archy-{}", package_id_spawn)] {
+                        crate::crash_recovery::mark_user_uninstalled(&handler.config.data_dir, id)
+                            .await;
+                        crate::crash_recovery::clear_installed(&handler.config.data_dir, id).await;
+                    }
                     // Inner handler already removed the package entry on
                     // success. Nothing more to do here.
                 }
@@ -330,7 +347,7 @@ impl RpcHandler {
         let package_id_spawn = package_id.clone();
         tokio::spawn(async move {
             match handler.handle_package_update(params).await {
-                Ok(_) => {
+                Ok(result) => {
                     info!("package.update {}: complete", package_id_spawn);
                     // Same reasoning as install: the merge_preserving_transitional
                     // helper treats Updating as RPC-owned, so we MUST write the
@@ -345,19 +362,49 @@ impl RpcHandler {
                     set_package_state(
                         &handler.state_manager,
                         &package_id_spawn,
-                        PackageState::Running,
+                        if result.get("status").and_then(|v| v.as_str()) == Some("staged") {
+                            PackageState::Stopped
+                        } else if result.get("status").and_then(|v| v.as_str())
+                            == Some("up-to-date")
+                        {
+                            pre_state.clone().unwrap_or(PackageState::Running)
+                        } else {
+                            PackageState::Running
+                        },
                     )
                     .await;
                 }
                 Err(e) => {
                     error!("package.update {} failed: {:#}", package_id_spawn, e);
                     install_log(&format!("UPDATE FAIL: {} — {:#}", package_id_spawn, e)).await;
-                    // Inner handler already ran rollback_update + cleared
-                    // update state, but be defensive: revert to pre-state
-                    // in case the inner flow died before its cleanup.
-                    if let Some(prev) = pre_state {
-                        set_package_state(&handler.state_manager, &package_id_spawn, prev).await;
+                    // Release the transitional overlay before asking the scanner
+                    // for real state. Prior Running is not proof of successful
+                    // rollback, and a failed preflight is not proof of Stopped.
+                    handler
+                        .state_manager
+                        .mutate_data(|data| {
+                            if let Some(entry) = data.package_data.get_mut(&package_id_spawn) {
+                                finish_failed_update(entry);
                             }
+                            data.notifications.retain(|item| {
+                                item.id != format!("update-failed-{package_id_spawn}")
+                            });
+                            data.notifications.push(crate::data_model::Notification {
+                                id: format!("update-failed-{package_id_spawn}"),
+                                level: crate::data_model::NotificationLevel::Error,
+                                title: format!("Could not update {package_id_spawn}"),
+                                message: format!(
+                                    "{e}. Runtime recovery does not roll back database changes."
+                                ),
+                                timestamp: chrono::Utc::now().to_rfc3339(),
+                                app_id: Some(package_id_spawn.clone()),
+                            });
+                            while data.notifications.len() > 20 {
+                                data.notifications.remove(0);
+                            }
+                        })
+                        .await;
+                    kick_scanner_and_wait(&handler).await;
                 }
             }
         });
@@ -377,53 +424,16 @@ impl RpcHandler {
 /// Matches what the inner handler's `set_install_progress` would do on first
 /// call, but fires before the spawn so the UI sees it immediately.
 async fn flip_to_installing(state_manager: &StateManager, package_id: &str) {
-    use crate::data_model::{Description, Manifest, PackageDataEntry, StaticFiles};
-    let (mut data, _) = state_manager.get_snapshot().await;
+    state_manager
+        .mutate_data(|data| {
             let entry = data
                 .package_data
                 .entry(package_id.to_string())
-        .or_insert_with(|| PackageDataEntry {
-            state: PackageState::Installing,
-            health: None,
-            exit_code: None,
-            static_files: StaticFiles {
-                license: String::new(),
-                instructions: String::new(),
-                // Leave icon empty during the transient Installing window:
-                // hardcoding `<id>.png` is wrong for ~half our apps (many use
-                // `.svg` / `.webp`), producing a broken-image flicker until
-                // the scanner refreshes the entry. The frontend's `icon`
-                // computed falls through to `curatedMap.get(id)?.icon` which
-                // has the correct extensions for known apps.
-                icon: String::new(),
-            },
-            manifest: Manifest {
-                id: package_id.to_string(),
-                title: package_id.to_string(),
-                version: String::new(),
-                description: Description {
-                    short: "Installing...".to_string(),
-                    long: String::new(),
-                },
-                release_notes: String::new(),
-                license: String::new(),
-                wrapper_repo: String::new(),
-                upstream_repo: String::new(),
-                support_site: String::new(),
-                marketing_site: String::new(),
-                donation_url: None,
-                author: None,
-                website: None,
-                interfaces: None,
-                tier: None,
-            },
-            installed: None,
-            install_progress: None,
-            uninstall_stage: None,
-            available_update: None,
-        });
+                .or_insert_with(|| super::progress::create_installing_entry(package_id));
+            entry.ui_ready = Some(false);
             entry.state = PackageState::Installing;
-    state_manager.update_data(data).await;
+        })
+        .await;
 }
 
 /// True when the failed install still has a real footprint: any container
@@ -481,7 +491,9 @@ async fn remove_entry_with_notification(
     id_prefix: &str,
     message: &str,
 ) {
-    let (mut data, _) = handler.state_manager.get_snapshot().await;
+    handler
+        .state_manager
+        .mutate_data(|data| {
             data.package_data.remove(package_id);
             data.notifications.push(crate::data_model::Notification {
                 id: format!("{id_prefix}-{package_id}"),
@@ -494,7 +506,8 @@ async fn remove_entry_with_notification(
             while data.notifications.len() > 20 {
                 data.notifications.remove(0);
             }
-    handler.state_manager.update_data(data).await;
+        })
+        .await;
 }
 
 /// Flip an existing entry's state and return the pre-flip value (or None if
@@ -504,11 +517,14 @@ async fn flip_package_state(
     package_id: &str,
     new_state: PackageState,
 ) -> Option<PackageState> {
-    let (mut data, _) = state_manager.get_snapshot().await;
+    state_manager
+        .mutate_data(|data| {
             let prev = data.package_data.get(package_id).map(|e| e.state.clone());
             if let Some(entry) = data.package_data.get_mut(package_id) {
+                if new_state != PackageState::Running {
+                    entry.ui_ready = Some(false);
+                }
                 entry.state = new_state;
-        state_manager.update_data(data).await;
             } else {
                 warn!(
                     "flip_package_state: no entry for {} — cannot flip",
@@ -516,6 +532,8 @@ async fn flip_package_state(
                 );
             }
             prev
+        })
+        .await
 }
 
 /// Set state unconditionally (no-op if entry no longer exists).
@@ -524,13 +542,18 @@ async fn set_package_state(
     package_id: &str,
     new_state: PackageState,
 ) {
-    let (mut data, _) = state_manager.get_snapshot().await;
+    state_manager
+        .mutate_data(|data| {
             if let Some(entry) = data.package_data.get_mut(package_id) {
                 if entry.state != new_state {
+                    if new_state != PackageState::Running {
+                        entry.ui_ready = Some(false);
+                    }
                     entry.state = new_state;
-            state_manager.update_data(data).await;
                 }
             }
+        })
+        .await
 }
 
 /// Set state and clear the uninstall_stage label. Used when an uninstall
@@ -541,12 +564,17 @@ async fn set_package_state_and_clear_uninstall_stage(
     package_id: &str,
     new_state: PackageState,
 ) {
-    let (mut data, _) = state_manager.get_snapshot().await;
+    state_manager
+        .mutate_data(|data| {
             if let Some(entry) = data.package_data.get_mut(package_id) {
+                if new_state != PackageState::Running {
+                    entry.ui_ready = Some(false);
+                }
                 entry.state = new_state;
                 entry.uninstall_stage = None;
-        state_manager.update_data(data).await;
             }
+        })
+        .await
 }
 
 /// Kick the container scanner to run immediately and wait for it to finish
@@ -579,3 +607,104 @@ async fn kick_scanner_and_wait(handler: &RpcHandler) {
     })
     .await;
 }
+
+fn finish_failed_update(entry: &mut crate::data_model::PackageDataEntry) {
+    if entry.state == PackageState::Updating {
+        entry.state = PackageState::Installed;
+    }
+    entry.install_progress = None;
+}
+#[cfg(test)]
+mod update_completion_tests {
+    use super::*;
+    #[tokio::test]
+    async fn update_image_byte_progress_preserves_owner_and_failure_releases_retry_gate() {
+        let directory = tempfile::tempdir().unwrap();
+        let mut config = crate::config::Config::default();
+        config.data_dir = directory.path().to_path_buf();
+        let state = Arc::new(StateManager::new());
+        let handler = RpcHandler::new(
+            config,
+            Arc::clone(&state),
+            Arc::new(crate::monitoring::MetricsStore::new()),
+            crate::session::SessionStore::new_for_tests(directory.path().join("sessions.json")),
+            None,
+            None,
+        )
+        .await
+        .unwrap();
+        state
+            .mutate_data(|data| {
+                let mut entry = super::super::progress::create_installing_entry("movie");
+                entry.state = PackageState::Running;
+                entry.ui_ready = Some(true);
+                data.package_data.insert("movie".into(), entry);
+            })
+            .await;
+        flip_package_state(&state, "movie", PackageState::Updating).await;
+        let update_ready = state.get_snapshot().await.0.package_data["movie"].ui_ready;
+        assert_eq!(update_ready, Some(false));
+        // Both calls happen even when an immutable image already exists locally.
+        for (downloaded, total) in [(0, 0), (100, 100)] {
+            handler
+                .set_install_progress("movie", downloaded, total)
+                .await;
+            let (snapshot, _) = state.get_snapshot().await;
+            let entry = &snapshot.package_data["movie"];
+            assert_eq!(entry.state, PackageState::Updating);
+            assert_eq!(entry.ui_ready, update_ready);
+            assert_eq!(
+                entry.install_progress.as_ref().unwrap().downloaded,
+                downloaded
+            );
+        }
+        RpcHandler::update_install_progress(&state, "movie", 50, 100).await;
+        handler
+            .set_install_phase("movie", crate::data_model::InstallPhase::Preparing)
+            .await;
+        handler
+            .set_install_message("movie", "Checking original services")
+            .await;
+        assert_eq!(
+            state.get_snapshot().await.0.package_data["movie"].state,
+            PackageState::Updating
+        );
+        state
+            .mutate_data(|data| finish_failed_update(data.package_data.get_mut("movie").unwrap()))
+            .await;
+        let (snapshot, _) = state.get_snapshot().await;
+        let entry = &snapshot.package_data["movie"];
+        assert_eq!(
+            entry.state,
+            PackageState::Installed,
+            "Failed update must release RPC transition ownership for scanner/retry admission"
+        );
+        assert!(entry.install_progress.is_none());
+        handler.set_install_progress("fresh-install", 1, 10).await;
+        let (snapshot, _) = state.get_snapshot().await;
+        let entry = &snapshot.package_data["fresh-install"];
+        assert_eq!(entry.state, PackageState::Installing);
+        assert_eq!(entry.ui_ready, Some(false));
+        assert_eq!(entry.install_progress.as_ref().unwrap().downloaded, 1);
+    }
+    #[test]
+    fn failure_releases_spinner_without_inventing_stopped_or_restored_runtime() {
+        let mut entry = super::super::progress::create_installing_entry("movie");
+        entry.state = PackageState::Updating;
+        finish_failed_update(&mut entry);
+        assert_eq!(entry.state, PackageState::Installed);
+        assert!(entry.install_progress.is_none());
+        for actual in [
+            PackageState::Running,
+            PackageState::Stopped,
+            PackageState::Exited,
+        ] {
+            entry.state = actual.clone();
+            finish_failed_update(&mut entry);
+            assert_eq!(
+                entry.state, actual,
+                "Fresh scanner evidence must win over old pre-update intent"
+            );
+        }
+    }
+}

core/archipelago/src/api/rpc/package/config.rs

@@ -526,7 +526,18 @@ pub(in crate::api::rpc) async fn get_containers_for_app(package_id: &str) -> Res
         .await
         .context("podman ps timed out while listing containers")?
         .context("Failed to list containers")?;
-    let stdout = String::from_utf8_lossy(&output.stdout);
+    containers_from_list_output(package_id, &output)
+}
+
+fn containers_from_list_output(
+    package_id: &str,
+    output: &std::process::Output,
+) -> Result<Vec<String>> {
+    anyhow::ensure!(
+        output.status.success(),
+        "podman ps failed while listing containers"
+    );
+    let stdout = std::str::from_utf8(&output.stdout).context("Invalid container list response")?;
     let all: Vec<&str> = stdout.lines().filter(|s| !s.is_empty()).collect();
 
     let patterns = all_container_names(package_id);
@@ -543,6 +554,32 @@ pub(in crate::api::rpc) async fn get_containers_for_app(package_id: &str) -> Res
 mod tests {
     use super::{all_container_names, get_data_dirs_for_app, get_health_check_args};
 
+    #[test]
+    fn failed_container_listing_is_not_an_absent_app() {
+        use std::os::unix::process::ExitStatusExt;
+        let mut output = std::process::Output {
+            status: std::process::ExitStatus::from_raw(1 << 8),
+            stdout: vec![],
+            stderr: b"store unavailable".to_vec(),
+        };
+        assert!(super::containers_from_list_output("node-demo-music", &output).is_err());
+        output.stdout = b"node-demo-music\n".to_vec();
+        assert!(super::containers_from_list_output("node-demo-music", &output).is_err());
+        output.status = std::process::ExitStatus::from_raw(0);
+        assert_eq!(
+            super::containers_from_list_output("node-demo-music", &output).unwrap(),
+            vec!["node-demo-music"]
+        );
+        output.stdout.clear();
+        assert!(
+            super::containers_from_list_output("node-demo-music", &output)
+                .unwrap()
+                .is_empty()
+        );
+        output.stdout = vec![0xff];
+        assert!(super::containers_from_list_output("node-demo-music", &output).is_err());
+    }
+
     #[test]
     fn bitcoin_variant_container_names_are_precise() {
         let core = all_container_names("bitcoin-core");
@@ -985,28 +1022,26 @@ pub(super) async fn get_app_config(
             )
         }
         "nginx-proxy-manager" => {
+            let storage = crate::container::npm::resolve_storage().await?;
             let admin_port = allocator
                 .allocate_or_get(app_id, 8081, 81)
                 .await
                 .unwrap_or(8081);
             let http_port = allocator
-                .allocate_or_get("nginx-proxy-manager-http", 8084, 80)
+                .allocate_or_get("nginx-proxy-manager-http", 8088, 80)
                 .await
-                .unwrap_or(8084);
+                .unwrap_or(8088);
             let https_port = allocator
                 .allocate_or_get("nginx-proxy-manager-https", 8444, 443)
                 .await
                 .unwrap_or(8444);
             (
                 vec![
-                    format!("{}:81", admin_port),
-                    format!("{}:80", http_port),
-                    format!("{}:443", https_port),
-                ],
-                vec![
-                    "/var/lib/archipelago/nginx-proxy-manager/data:/data".to_string(),
-                    "/var/lib/archipelago/nginx-proxy-manager/letsencrypt:/etc/letsencrypt".to_string(),
+                    format!("127.0.0.1:{}:81", admin_port),
+                    format!("127.0.0.1:{}:80", http_port),
+                    format!("127.0.0.1:{}:443", https_port),
                 ],
+                storage.bind_mounts(),
                 vec![],
                 None,
                 None,

core/archipelago/src/api/rpc/package/dependencies.rs

@@ -22,6 +22,18 @@ const ARCHIVAL_BITCOIN_DEPENDENCY: &str = "bitcoin:archival";
 /// hardcoded id list below — a new app just declares the dependency instead
 /// of needing a code change here.
 fn manifest_declares_archival_bitcoin(package_id: &str) -> bool {
+    // Registry-only apps need the same guard as OTA-bundled manifests. Honor
+    // the verified catalog's effective manifest before the disk fallback.
+    if let Some((_, value)) = crate::container::app_catalog::catalog_manifest_values()
+        .into_iter()
+        .find(|(id, _)| id == package_id)
+    {
+        if let Some(manifest) =
+            crate::container::app_catalog::catalog_manifest_overlay(package_id, value)
+        {
+            return dependency_list_declares_archival_bitcoin(&manifest.app.dependencies);
+        }
+    }
     for apps_dir in manifest_apps_dirs() {
         let path = apps_dir.join(package_id).join("manifest.yml");
         let Ok(contents) = std::fs::read_to_string(&path) else {
@@ -1055,6 +1067,14 @@ mod tests {
         // edit to `requires_unpruned_bitcoin`.
         assert!(manifest_declares_archival_bitcoin("electrumx"));
         assert!(manifest_declares_archival_bitcoin("mempool"));
+        let angor = archipelago_container::AppManifest::parse(include_str!(concat!(
+            env!("CARGO_MANIFEST_DIR"),
+            "/../../apps/angor-indexer/manifest.yml"
+        )))
+        .unwrap();
+        assert!(dependency_list_declares_archival_bitcoin(
+            &angor.app.dependencies
+        ));
         // An app whose manifest exists but never declares the marker.
         assert!(!manifest_declares_archival_bitcoin("bitcoin-knots"));
         // An id with no manifest on disk at all.

core/archipelago/src/api/rpc/package/install.rs

@@ -280,6 +280,10 @@ impl RpcHandler {
             .and_then(|v| v.as_str())
             .ok_or_else(|| anyhow::anyhow!("Missing package id"))?;
         validate_app_id(package_id)?;
+        let lifecycle_guard =
+            crate::container::update_transaction::Guard::acquire(&self.config.data_dir)?;
+        lifecycle_guard.require_clear()?;
+        lifecycle_guard.require_unheld(&super::config::all_container_names(package_id))?;
 
         let docker_image = params
             .get("dockerImage")
@@ -326,6 +330,10 @@ impl RpcHandler {
         // an older version pins it so install_fresh resolves that image and the
         // update badge stays suppressed. See docs/bitcoin-multi-version-design.md.
         if matches!(package_id, "bitcoin-core" | "bitcoin-knots") {
+            if let Some(value) = params.get("prune") {
+                let prune = value.as_bool().context("prune must be a boolean")?;
+                crate::settings::bitcoin_storage::save(&self.config.data_dir, prune).await?;
+            }
             if let Some(version) = params.get("version").and_then(|v| v.as_str()) {
                 persist_install_version_selection(package_id, version).await;
             }
@@ -541,7 +549,7 @@ impl RpcHandler {
         // Keep legacy install flow as default while migration is in progress.
         if orchestrator_managed {
             let orchestrator_app_id = orchestrator_install_app_id(package_id);
-            self.set_install_phase(package_id, InstallPhase::CreatingContainer)
+            self.set_install_phase(package_id, InstallPhase::PreparingApp)
                 .await;
             install_log(&format!(
                 "INSTALL ORCH: {} — attempting orchestrator install as {}",
@@ -569,6 +577,9 @@ impl RpcHandler {
                             "message": format!("Package {} installed and started", package_id)
                         }));
                     }
+                    Err(e) if e.downcast_ref::<crate::container::prod_orchestrator::InstallPrerequisiteError>().is_some() => {
+                        return Err(super::dependencies::DependencyGateError(e.to_string()).into());
+                    }
                     Err(e) if is_unknown_app_id_error(&e) => {
                         info!(
                             "Install {}: orchestrator has no manifest mapping yet, falling back to legacy installer",
@@ -686,7 +697,11 @@ impl RpcHandler {
             // These standalone web UIs have repeatedly lost host listeners
             // under Podman's rootless pasta backend while staying healthy internally.
             // Use slirp4netns/rootlessport for this standalone web UI.
-            run_args.push("--network=slirp4netns:allow_host_loopback=true");
+            run_args.push(if package_id == "nginx-proxy-manager" {
+                "--network=slirp4netns:allow_host_loopback=true,cidr=169.254.1.0/24"
+            } else {
+                "--network=slirp4netns:allow_host_loopback=true"
+            });
         } else if needs_archy_net(package_id) {
             // Create archy-net if it doesn't exist (idempotent — "already exists" is fine)
             match tokio::process::Command::new("podman")
@@ -1561,88 +1576,8 @@ autopilot.active=false\n",
                 super::pine_ha::restart_home_assistant_if_running().await;
             }
         }
-        if package_id == "filebrowser" {
-            // Generate a random password (32 bytes, hex-encoded)
-            let mut buf = [0u8; 32];
-            rand::RngCore::fill_bytes(&mut rand::rngs::OsRng, &mut buf);
-            let password = hex::encode(buf);
-
-            let client = match reqwest::Client::builder()
-                .timeout(std::time::Duration::from_secs(10))
-                .build()
-            {
-                Ok(c) => c,
-                Err(e) => {
-                    tracing::warn!("Failed to create HTTP client for FileBrowser hook: {}", e);
-                    return;
-                }
-            };
-
-            // Retry loop: FileBrowser may take time to initialize its SQLite database
-            let mut password_changed = false;
-            for attempt in 0..6u32 {
-                let delay = if attempt == 0 { 5 } else { 10 };
-                tokio::time::sleep(std::time::Duration::from_secs(delay)).await;
-
-                // Try to log in with default credentials
-                let login_res = client
-                    .post("http://127.0.0.1:8083/api/login")
-                    .json(&serde_json::json!({"username": "admin", "password": "admin"}))
-                    .send()
-                    .await;
-
-                let token = match login_res {
-                    Ok(resp) if resp.status().is_success() => match resp.text().await {
-                        Ok(t) => t.trim_matches('"').to_string(),
-                        Err(_) => continue,
-                    },
-                    _ => {
-                        debug!("FileBrowser not ready (attempt {}/6)", attempt + 1);
-                        continue;
-                    }
-                };
-
-                // Change admin password
-                let change_res = client
-                    .put("http://127.0.0.1:8083/api/users/1")
-                    .header("X-Auth", &token)
-                    .json(&serde_json::json!({"password": password}))
-                    .send()
-                    .await;
-
-                match change_res {
-                    Ok(resp) if resp.status().is_success() => {
-                        let secret_dir = "/var/lib/archipelago/secrets/filebrowser";
-                        if let Err(e) = tokio::fs::create_dir_all(secret_dir).await {
-                            tracing::warn!("Failed to create filebrowser secrets dir: {}", e);
-                        }
-                        let pw_path = format!("{}/password", secret_dir);
-                        if let Err(e) = tokio::fs::write(&pw_path, &password).await {
-                            tracing::warn!("Failed to write filebrowser password: {}", e);
-                        }
-                        // Set restrictive permissions on the password file
-                        #[cfg(unix)]
-                        {
-                            use std::os::unix::fs::PermissionsExt;
-                            let _ = std::fs::set_permissions(
-                                &pw_path,
-                                std::fs::Permissions::from_mode(0o600),
-                            );
-                        }
-                        info!("FileBrowser admin password secured (default credentials replaced)");
-                        password_changed = true;
-                        break;
-                    }
-                    _ => continue,
-                }
-            }
-            if !password_changed {
-                tracing::warn!(
-                    "FileBrowser password could not be changed after 6 attempts — \
-                     default credentials (admin/admin) remain active"
-                );
-            }
-        }
+        // File Browser credentials are provisioned and verified before the
+        // server starts. Never attempt a default-password change after launch.
 
         // Auto-configure Tor hidden service for protocol services (LND, ElectrumX, Bitcoin)
         {
@@ -1695,32 +1630,10 @@ autopilot.active=false\n",
             patch_indeedhub_nostr_provider().await;
         }
 
-        // Gitea: keep it on its native host port (3001). The UI opens Gitea
-        // in a new tab on that direct port so absolute asset URLs must be
-        // rooted at the host port rather than Archipelago's /app/gitea/ path.
-        if package_id == "gitea" {
-            let _ = tokio::fs::remove_file("/etc/nginx/conf.d/gitea-iframe.conf").await;
-
-            // Set ROOT_URL to the direct launch route so links/assets stay
-            // anchored under the same origin Gitea is launched from.
-            let host_ip = &self.config.host_ip;
-            let _ = tokio::process::Command::new("podman")
-                .args(["exec", "gitea", "sh", "-c",
-                       &format!("grep -q ROOT_URL /data/gitea/conf/app.ini && sed -i 's|ROOT_URL.*|ROOT_URL = http://{}:3001/|' /data/gitea/conf/app.ini || true", host_ip)])
-                .output()
-                .await;
-            // Also ensure X_FRAME_OPTIONS is empty so Gitea doesn't send the header
-            let _ = tokio::process::Command::new("podman")
-                .args(["exec", "gitea", "sh", "-c",
-                       "grep -q X_FRAME_OPTIONS /data/gitea/conf/app.ini && sed -i 's|X_FRAME_OPTIONS.*|X_FRAME_OPTIONS =|' /data/gitea/conf/app.ini || sed -i '/^\\[security\\]/a X_FRAME_OPTIONS =' /data/gitea/conf/app.ini"])
-                .output()
-                .await;
-
-            info!(
-                "Gitea: ROOT_URL set to http://{}:3001/, X_FRAME_OPTIONS cleared",
-                host_ip
-            );
-        }
+        // Gitea owns its public URL and security settings in app.ini, including
+        // values chosen in its first-run setup. Do not rewrite operator values
+        // or claim success from best-effort grep/sed commands. The app gate
+        // fronts its declared HTTP port and handles frame headers separately.
 
         if package_id == "nextcloud" {
             let host_ip = &self.config.host_ip;
@@ -1927,10 +1840,10 @@ autopilot.active=false\n",
     }
 
     pub(in crate::api::rpc) async fn handle_filebrowser_token(&self) -> Result<serde_json::Value> {
-        let secret_path = "/var/lib/archipelago/secrets/filebrowser/password";
-        let password = tokio::fs::read_to_string(secret_path)
-            .await
-            .unwrap_or_else(|_| "admin".to_string());
+        let credentials = crate::container::filebrowser::cloud_credentials(std::path::Path::new(
+            "/var/lib/archipelago/secrets/filebrowser",
+        ))
+        .await?;
 
         let client = reqwest::Client::builder()
             .timeout(std::time::Duration::from_secs(10))
@@ -1939,7 +1852,7 @@ autopilot.active=false\n",
 
         let resp = client
             .post("http://127.0.0.1:8083/api/login")
-            .json(&serde_json::json!({"username": "admin", "password": password}))
+            .json(&serde_json::json!({"username": credentials.username, "password": credentials.password}))
             .send()
             .await
             .context("Failed to connect to FileBrowser")?;
@@ -1969,14 +1882,36 @@ autopilot.active=false\n",
         super::validation::validate_app_id(app_id)?;
 
         if app_id == "filebrowser" {
-            let password =
-                tokio::fs::read_to_string("/var/lib/archipelago/secrets/filebrowser/password")
-                    .await
-                    .map(|p| p.trim().to_string())
-                    .unwrap_or_else(|_| "admin".to_string());
+            let credentials = crate::container::filebrowser::cloud_credentials(
+                std::path::Path::new("/var/lib/archipelago/secrets/filebrowser"),
+            )
+            .await?;
             return Ok(serde_json::json!({
                 "title": "File Browser credentials",
                 "description": "Use these credentials when File Browser asks you to sign in.",
+                "credentials": [
+                    { "label": "Username", "value": credentials.username },
+                    { "label": "Password", "value": credentials.password, "sensitive": true }
+                ]
+            }));
+        }
+
+        if app_id == "datum" {
+            // This is the same platform-owned secret injected into DATUM and
+            // Gashboard. Never publish it in the manifest or a UI fallback.
+            let password = tokio::fs::read_to_string(
+                self.config.data_dir.join("secrets/datum-admin-password"),
+            )
+            .await
+            .context("DATUM credentials are not available yet; wait for installation to finish")?;
+            let password = password.trim();
+            anyhow::ensure!(
+                !password.is_empty(),
+                "DATUM administrator password is empty"
+            );
+            return Ok(serde_json::json!({
+                "title": "DATUM Gateway login",
+                "description": "Use this password when DATUM asks you to unlock configuration. In Config, set your Bitcoin payout address. Point miners at this node's IP address on Stratum port 23334 (stratum+tcp://NODE-IP:23334). Gashboard connects automatically.",
                 "credentials": [
                     { "label": "Username", "value": "admin" },
                     { "label": "Password", "value": password, "sensitive": true }
@@ -2049,25 +1984,8 @@ fn parse_setup_token(lines: &[&str]) -> Option<String> {
 }
 
 async fn cleanup_stale_package_ports(package_id: &str) {
-    match package_id {
-        "grafana" => cleanup_stale_pasta_port("3000").await,
-        "homeassistant" | "home-assistant" => cleanup_stale_pasta_port("8123").await,
-        "searxng" => cleanup_stale_pasta_port("8888").await,
-        "uptime-kuma" => cleanup_stale_pasta_port("3002").await,
-        "gitea" => {
-            cleanup_stale_pasta_port("3001").await;
-            cleanup_stale_pasta_port("2222").await;
-            cleanup_stale_pasta_port("3000").await;
-        }
-        "nginx-proxy-manager" => {
-            cleanup_stale_pasta_port("8081").await;
-            cleanup_stale_pasta_port("8084").await;
-            cleanup_stale_pasta_port("8444").await;
-        }
-        "nextcloud" => cleanup_stale_pasta_port("8085").await,
-        "portainer" => cleanup_stale_pasta_port("9000").await,
-        _ => {}
-    }
+    // Never kill by port: another app or the management gate may own it.
+    crate::container::ghost_reaper::reap_for_app(package_id).await;
 }
 
 fn install_command_tail(
@@ -2192,93 +2110,11 @@ async fn cleanup_start_conflict(package_id: &str, stderr: &str) -> bool {
         return true;
     }
 
-    match package_id {
-        "grafana"
-            if stderr.contains("pasta failed") || stderr.contains("address already in use") =>
-        {
-            cleanup_stale_pasta_port("3000").await;
-            true
+    if stderr.contains("pasta failed") || stderr.contains("address already in use") {
+        crate::container::ghost_reaper::reap_for_app(package_id).await;
+        return true;
     }
-        "homeassistant" | "home-assistant"
-            if stderr.contains("pasta failed") || stderr.contains("address already in use") =>
-        {
-            cleanup_stale_pasta_port("8123").await;
-            true
-        }
-        "searxng"
-            if stderr.contains("pasta failed") || stderr.contains("address already in use") =>
-        {
-            cleanup_stale_pasta_port("8888").await;
-            true
-        }
-        "uptime-kuma"
-            if stderr.contains("pasta failed") || stderr.contains("address already in use") =>
-        {
-            cleanup_stale_pasta_port("3002").await;
-            true
-        }
-        "gitea" if stderr.contains("pasta failed") || stderr.contains("address already in use") => {
-            cleanup_stale_pasta_port("3001").await;
-            cleanup_stale_pasta_port("2222").await;
-            cleanup_stale_pasta_port("3000").await;
-            true
-        }
-        "nginx-proxy-manager"
-            if stderr.contains("pasta failed") || stderr.contains("address already in use") =>
-        {
-            cleanup_stale_pasta_port("8081").await;
-            cleanup_stale_pasta_port("8084").await;
-            cleanup_stale_pasta_port("8444").await;
-            true
-        }
-        "nextcloud"
-            if stderr.contains("pasta failed") || stderr.contains("address already in use") =>
-        {
-            cleanup_stale_pasta_port("8085").await;
-            true
-        }
-        "portainer"
-            if stderr.contains("pasta failed") || stderr.contains("address already in use") =>
-        {
-            cleanup_stale_pasta_port("9000").await;
-            true
-        }
-        _ => false,
-    }
-}
-
-async fn cleanup_stale_pasta_port(port: &str) {
-    // NEVER kill our own process. The daemon holds catalog app ports over
-    // IPv6 (the mesh app-port relay), so a blunt `fuser -k <port>/tcp` would
-    // terminate archipelago itself mid-install — installs failed and apps
-    // vanished on a test node 2026-07-27. Kill every listener on the port
-    // EXCEPT our PID (and our process group), leaving the relay/daemon alive.
-    let self_pid = std::process::id();
-    let kill_listener = format!(
-        "ss -ltnp 'sport = :{port}' 2>/dev/null | sed -n 's/.*pid=\\([0-9]*\\).*/\\1/p' | \
-         while read p; do [ \"$p\" = \"{self_pid}\" ] || kill \"$p\" 2>/dev/null; done || true",
-    );
-    let _ = tokio::process::Command::new("sh")
-        .args(["-c", &kill_listener])
-        .output()
-        .await;
-
-    // sudo fuser -k, but exclude our own PID: fuser prints the PIDs holding
-    // the port; kill each except self. (`fuser -k` has no exclusion flag.)
-    let fuser_kill = format!(
-        "for p in $(sudo fuser {port}/tcp 2>/dev/null); do [ \"$p\" = \"{self_pid}\" ] || sudo kill \"$p\" 2>/dev/null; done || true",
-    );
-    let _ = tokio::process::Command::new("sh")
-        .args(["-c", &fuser_kill])
-        .output()
-        .await;
-
-    let pattern = format!("pasta.*{}", port);
-    let _ = tokio::process::Command::new("pkill")
-        .args(["-f", &pattern])
-        .output()
-        .await;
-    tokio::time::sleep(std::time::Duration::from_secs(1)).await;
+    false
 }
 
 async fn repair_nextcloud_permissions() {

core/archipelago/src/api/rpc/package/progress.rs

@@ -14,12 +14,19 @@ impl RpcHandler {
     /// the rare case where the pull stream actually parses, but podman
     /// almost never emits parseable progress on a piped stderr.
     pub(super) async fn set_install_progress(&self, package_id: &str, downloaded: u64, size: u64) {
-        let (mut data, _rev) = self.state_manager.get_snapshot().await;
+        self.state_manager
+            .mutate_data(|data| {
                 let entry = data
                     .package_data
                     .entry(package_id.to_string())
                     .or_insert_with(|| create_installing_entry(package_id));
+                // Image pulls also report byte progress during updates, including
+                // the local immutable-image shortcut. Preserve the RPC owner so
+                // update failure cleanup can release its transitional state.
+                if entry.state != PackageState::Updating {
+                    entry.ui_ready = Some(false);
                     entry.state = PackageState::Installing;
+                }
                 let existing_phase = entry.install_progress.as_ref().and_then(|p| p.phase);
                 entry.install_progress = Some(InstallProgress {
                     size,
@@ -27,7 +34,8 @@ impl RpcHandler {
                     phase: existing_phase,
                     message: None,
                 });
-        self.state_manager.update_data(data).await;
+            })
+            .await;
     }
 
     /// Set the install pipeline phase and broadcast. This is the
@@ -35,7 +43,8 @@ impl RpcHandler {
     /// percentage and a user-facing label. Byte counters are retained
     /// for the rare case podman emits parseable progress.
     pub(super) async fn set_install_phase(&self, package_id: &str, phase: InstallPhase) {
-        let (mut data, _rev) = self.state_manager.get_snapshot().await;
+        self.state_manager
+            .mutate_data(|data| {
                 let entry = data
                     .package_data
                     .entry(package_id.to_string())
@@ -45,6 +54,7 @@ impl RpcHandler {
                 // Updates use Updating state — the wrapper has already flipped
                 // state to Updating, so don't clobber it.
                 if entry.state != PackageState::Updating {
+                    entry.ui_ready = Some(false);
                     entry.state = PackageState::Installing;
                 }
                 let (size, downloaded) = entry
@@ -58,18 +68,21 @@ impl RpcHandler {
                     phase: Some(phase),
                     message: None,
                 });
-        self.state_manager.update_data(data).await;
+            })
+            .await;
     }
 
     /// Set a user-facing install status message (e.g. "Waiting for Bitcoin
     /// to start…") without disturbing the current phase/byte counters.
     pub(super) async fn set_install_message(&self, package_id: &str, message: &str) {
-        let (mut data, _rev) = self.state_manager.get_snapshot().await;
+        self.state_manager
+            .mutate_data(|data| {
                 let entry = data
                     .package_data
                     .entry(package_id.to_string())
                     .or_insert_with(|| create_installing_entry(package_id));
                 if entry.state != PackageState::Updating {
+                    entry.ui_ready = Some(false);
                     entry.state = PackageState::Installing;
                 }
                 let (size, downloaded, phase) = entry
@@ -83,28 +96,33 @@ impl RpcHandler {
                     phase,
                     message: Some(message.to_string()),
                 });
-        self.state_manager.update_data(data).await;
+            })
+            .await;
     }
 
     /// Clear install progress after pull completes or fails.
     pub(super) async fn clear_install_progress(&self, package_id: &str) {
-        let (mut data, _rev) = self.state_manager.get_snapshot().await;
+        self.state_manager
+            .mutate_data(|data| {
                 if let Some(entry) = data.package_data.get_mut(package_id) {
                     entry.install_progress = None;
                 }
-        self.state_manager.update_data(data).await;
+            })
+            .await;
     }
 
     /// Set the uninstall stage label so the UI can show what's happening
     /// instead of a generic spinner. Each call broadcasts a state change
     /// — call sparingly (one per pipeline phase, not per container).
     pub(super) async fn set_uninstall_stage(&self, package_id: &str, stage: &str) {
-        let (mut data, _rev) = self.state_manager.get_snapshot().await;
+        self.state_manager
+            .mutate_data(|data| {
                 if let Some(entry) = data.package_data.get_mut(package_id) {
                     entry.uninstall_stage = Some(stage.to_string());
                     entry.state = crate::data_model::PackageState::Removing;
                 }
-        self.state_manager.update_data(data).await;
+            })
+            .await;
     }
 
     /// Update install progress (static method for use in async closures).
@@ -114,7 +132,8 @@ impl RpcHandler {
         downloaded: u64,
         total: u64,
     ) {
-        let (mut data, _rev) = state_manager.get_snapshot().await;
+        state_manager
+            .mutate_data(|data| {
                 let entry = data
                     .package_data
                     .entry(package_id.to_string())
@@ -126,23 +145,23 @@ impl RpcHandler {
                     phase: existing_phase,
                     message: None,
                 });
-        state_manager.update_data(data).await;
+            })
+            .await;
     }
 }
 
-/// Create a minimal PackageDataEntry for a package being installed.
-fn create_installing_entry(package_id: &str) -> PackageDataEntry {
-    PackageDataEntry {
+/// Seed an Installing entry from its manifest before any container exists.
+pub(super) fn create_installing_entry(package_id: &str) -> PackageDataEntry {
+    let mut entry = PackageDataEntry {
+        ui_ready: None,
         state: PackageState::Installing,
         health: None,
         exit_code: None,
         static_files: StaticFiles {
             license: String::new(),
             instructions: String::new(),
-            // Empty icon: hardcoding `<id>.png` is wrong for apps that use
-            // `.svg` or `.webp` assets and produces a broken-image flicker.
-            // The frontend's `icon` computed falls through to the curated
-            // map which has correct extensions for known apps.
+            // Filled below from the manifest, without guessing the extension.
+            // Unmanifested apps can still use the frontend catalog fallback.
             icon: String::new(),
         },
         manifest: Manifest {
@@ -169,7 +188,9 @@ fn create_installing_entry(package_id: &str) -> PackageDataEntry {
         install_progress: None,
         uninstall_stage: None,
         available_update: None,
-    }
+    };
+    crate::container::docker_packages::apply_manifest_presentation(package_id, &mut entry);
+    entry
 }
 
 /// Parse podman pull progress output.

core/archipelago/src/api/rpc/package/runtime.rs

@@ -60,6 +60,10 @@ impl RpcHandler {
             .and_then(|v| v.as_str())
             .ok_or_else(|| anyhow::anyhow!("Missing package id"))?;
         validate_app_id(package_id)?;
+        let lifecycle_guard =
+            crate::container::update_transaction::Guard::acquire(&self.config.data_dir)?;
+        lifecycle_guard.require_clear()?;
+        lifecycle_guard.require_unheld(&super::config::all_container_names(package_id))?;
         // A cuprate node that starts on a too-small disk fills it and takes
         // Archipelago down with it (no upstream pruning — see
         // dependencies::check_cuprate_disk_compatibility). Fail the start
@@ -104,9 +108,10 @@ impl RpcHandler {
         let op_lock = app_op_lock(package_id);
         let data_dir = self.config.data_dir.clone();
         tokio::spawn(async move {
+            let _lifecycle_guard = lifecycle_guard;
             let _op_guard = op_lock.lock().await;
             let result = if let Some(orchestrator) = orchestrator.as_ref() {
-                do_orchestrator_package_start(orchestrator.as_ref(), &to_start).await
+                do_orchestrator_package_start(orchestrator.as_ref(), &to_start, &data_dir).await
             } else {
                 do_package_start(&to_start).await
             };
@@ -126,7 +131,19 @@ impl RpcHandler {
                 Err(e) => {
                     tracing::error!("package.start {} failed: {:#}", package_id_owned, e);
                     install_log(&format!("START FAIL: {} — {:#}", package_id_owned, e)).await;
-                    if let Some(prev) = pre_state {
+                    if e.downcast_ref::<crate::container::prod_orchestrator::StagedCleanupFailure>()
+                        .is_some()
+                    {
+                        // Installed is neutral and scanner-owned. Restoring the
+                        // prior Stopped state would conceal a failed cleanup;
+                        // keeping Starting would prevent scanner convergence.
+                        set_package_state(
+                            &state_manager,
+                            &package_id_owned,
+                            PackageState::Installed,
+                        )
+                        .await;
+                    } else if let Some(prev) = pre_state {
                         set_package_state(&state_manager, &package_id_owned, prev).await;
                     } else {
                         warn!(
@@ -155,6 +172,10 @@ impl RpcHandler {
             .and_then(|v| v.as_str())
             .ok_or_else(|| anyhow::anyhow!("Missing package id"))?;
         validate_app_id(package_id)?;
+        let lifecycle_guard =
+            crate::container::update_transaction::Guard::acquire(&self.config.data_dir)?;
+        lifecycle_guard.require_clear()?;
+        lifecycle_guard.require_unheld(&super::config::all_container_names(package_id))?;
 
         let single_orchestrator_app =
             self.orchestrator.is_some() && uses_single_orchestrator_app(package_id);
@@ -218,10 +239,12 @@ impl RpcHandler {
         .await;
 
         let op_lock = app_op_lock(package_id);
+        let data_dir = self.config.data_dir.clone();
         tokio::spawn(async move {
+            let _lifecycle_guard = lifecycle_guard;
             let _op_guard = op_lock.lock().await;
             let result = if let Some(orchestrator) = orchestrator.as_ref() {
-                do_orchestrator_package_stop(orchestrator.as_ref(), &to_stop).await
+                do_orchestrator_package_stop(orchestrator.as_ref(), &to_stop, &data_dir).await
             } else {
                 do_package_stop(&containers).await
             };
@@ -257,6 +280,10 @@ impl RpcHandler {
             .and_then(|v| v.as_str())
             .ok_or_else(|| anyhow::anyhow!("Missing package id"))?;
         validate_app_id(package_id)?;
+        let lifecycle_guard =
+            crate::container::update_transaction::Guard::acquire(&self.config.data_dir)?;
+        lifecycle_guard.require_clear()?;
+        lifecycle_guard.require_unheld(&super::config::all_container_names(package_id))?;
         // Restart is stop + recreate, so on a disk that shrank below the cuprate
         // minimum after install it resumes the doomed unprunable sync just like
         // start would — same gate, same "fail before clearing user-stopped /
@@ -319,9 +346,10 @@ impl RpcHandler {
         let op_lock = app_op_lock(package_id);
         let data_dir = self.config.data_dir.clone();
         tokio::spawn(async move {
+            let _lifecycle_guard = lifecycle_guard;
             let _op_guard = op_lock.lock().await;
             let result = if let Some(orchestrator) = orchestrator.as_ref() {
-                do_orchestrator_package_restart(orchestrator.as_ref(), &to_restart).await
+                do_orchestrator_package_restart(orchestrator.as_ref(), &to_restart, &data_dir).await
             } else {
                 do_package_restart(&containers).await
             };
@@ -362,6 +390,10 @@ impl RpcHandler {
             .and_then(|v| v.as_str())
             .ok_or_else(|| anyhow::anyhow!("Missing package id"))?;
         validate_app_id(package_id)?;
+        let lifecycle_guard =
+            crate::container::update_transaction::Guard::acquire(&self.config.data_dir)?;
+        lifecycle_guard.require_clear()?;
+        lifecycle_guard.require_unheld(&super::config::all_container_names(package_id))?;
         let preserve_data = params
             .get("preserve_data")
             .and_then(|v| v.as_bool())
@@ -841,17 +873,24 @@ async fn do_package_start(to_start: &[String]) -> Result<()> {
 async fn do_orchestrator_package_start(
     orchestrator: &dyn crate::container::traits::ContainerOrchestrator,
     to_start: &[String],
+    data_dir: &std::path::Path,
 ) -> Result<()> {
+    for name in to_start {
+        orchestrator.validate_start(name).await?;
+    }
     let mut errors = Vec::new();
     for (i, name) in to_start.iter().enumerate() {
         if i > 0 {
             tokio::time::sleep(std::time::Duration::from_secs(2)).await;
         }
+        let managed = crate::container::supervised_update::installed_unit(data_dir, name)?.is_some();
+        if !managed {
             repair_before_package_start(name).await;
             wait_before_package_start(name).await;
+        }
         match orchestrator.start(name).await {
             Ok(()) => wait_after_orchestrator_start(name).await,
-            Err(e) if is_unknown_app_id_error(&e) => {
+            Err(e) if !managed && is_unknown_app_id_error(&e) => {
                 // Collect instead of `?`: aborting here skipped every later
                 // stack member (mempool gate flakes #73/#74 — see
                 // order_present_containers).
@@ -871,8 +910,10 @@ async fn do_orchestrator_package_start(
         Err(anyhow::anyhow!("Start failed: {}", errors.join("; ")))
     } else {
         for name in to_start {
+            if crate::container::supervised_update::installed_unit(data_dir, name)?.is_none() {
                 ensure_runtime_host_port_listener(name).await?;
             }
+        }
         Ok(())
     }
 }
@@ -1100,12 +1141,14 @@ async fn podman_start_container(container_name: &str) -> Result<Output> {
 async fn do_orchestrator_package_stop(
     orchestrator: &dyn crate::container::traits::ContainerOrchestrator,
     containers: &[String],
+    data_dir: &std::path::Path,
 ) -> Result<()> {
     let mut errors = Vec::new();
     for name in containers {
+        let managed = crate::container::supervised_update::installed_unit(data_dir, name)?.is_some();
         match orchestrator.stop(name).await {
             Ok(()) => {}
-            Err(e) if is_unknown_app_id_error(&e) => {
+            Err(e) if !managed && is_unknown_app_id_error(&e) => {
                 if let Err(e) = do_package_stop(&[name.clone()]).await {
                     errors.push(format!("{}: {:#}", name, e));
                 }
@@ -1114,7 +1157,7 @@ async fn do_orchestrator_package_stop(
             // stop removes the --rm container before the orchestrator's
             // defensive `podman stop` fallback probes it, and a stack member
             // can be absent outright (stopped earlier, or never revived).
-            Err(e) if is_missing_container_error(&format!("{:#}", e)) => {
+            Err(e) if !managed && is_missing_container_error(&format!("{:#}", e)) => {
                 tracing::debug!(container = %name, error = %e, "stop: container already absent — treating as stopped");
             }
             Err(e) => {
@@ -1200,7 +1243,7 @@ async fn cascade_restart_address_caching_dependents(
         let prev = flip_package_state(state_manager, dep, PackageState::Restarting).await;
         let target = vec![dep.to_string()];
         let result = if let Some(orch) = orchestrator {
-            do_orchestrator_package_restart(orch.as_ref(), &target).await
+            do_orchestrator_package_restart(orch.as_ref(), &target, data_dir).await
         } else {
             do_package_restart(&target).await
         };
@@ -1268,9 +1311,14 @@ fn uses_single_orchestrator_app(package_id: &str) -> bool {
 async fn do_orchestrator_package_restart(
     orchestrator: &dyn crate::container::traits::ContainerOrchestrator,
     to_restart: &[String],
+    data_dir: &std::path::Path,
 ) -> Result<()> {
-    do_orchestrator_package_stop(orchestrator, to_restart).await?;
-    do_orchestrator_package_start(orchestrator, to_restart).await
+    for name in to_restart {
+        orchestrator.validate_start(name).await?;
+    }
+    let stop_order: Vec<String> = to_restart.iter().rev().cloned().collect();
+    do_orchestrator_package_stop(orchestrator, &stop_order, data_dir).await?;
+    do_orchestrator_package_start(orchestrator, to_restart, data_dir).await
 }
 
 /// Stop all containers with their per-container graceful-shutdown timeout.
@@ -1431,10 +1479,9 @@ async fn repair_before_package_start(container_name: &str) {
     // published port and the data-dir file locks, so the replacement either
     // fails to bind (`address already in use`) or starts and dies on the
     // lock — and `Restart=always` loops it there forever. Ordered before
-    // the port cleanup below: killing the owner is what actually frees the
-    // port, and the port sweep alone cannot tell a ghost from a live app.
+    // starting the replacement. A port sweep cannot distinguish a ghost
+    // from the dashboard gate or another live app and must never kill it.
     crate::container::ghost_reaper::reap_for_app(container_name).await;
-    cleanup_runtime_host_ports(container_name).await;
 }
 
 async fn wait_before_package_start(container_name: &str) {
@@ -1577,42 +1624,110 @@ async fn repair_netbird_network() {
 }
 
 async fn repair_nginx_proxy_manager_container() {
-    repair_nginx_proxy_manager_dirs().await;
-    if !nginx_proxy_manager_has_legacy_admin_port().await {
-        cleanup_nginx_proxy_manager_ports().await;
+    // Quadlet owns managed containers; its backed-up reconciliation applies
+    // port and mount changes. Never remove a systemd-owned container here.
+    if crate::container::quadlet::unit_exists("nginx-proxy-manager").await {
         return;
     }
+    // Serialize repair so a second caller cannot overlap a replacement.
+    static REPAIR: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
+    let _repair = REPAIR.lock().await;
+    if !nginx_proxy_manager_has_legacy_admin_port().await {
+        return;
+    }
+    if let Err(error) = repair_legacy_nginx_proxy_manager().await {
+        tracing::warn!(error = %error, "NPM legacy repair failed; persistent state preserved");
+    }
+}
 
-    install_log(
-        "START REPAIR: nginx-proxy-manager - recreating stale container using host port 8081",
+const NPM_PREVIOUS_CONTAINER: &str = "archy-npm-upgrade-previous";
+
+async fn restore_failed_npm_repair() -> Result<()> {
+    let removed = podman_control(&["rm", "-f", "--ignore", "nginx-proxy-manager"]).await?;
+    anyhow::ensure!(
+        removed.status.success(),
+        "cannot remove failed NPM replacement; previous container retained"
+    );
+    let renamed =
+        podman_control(&["rename", NPM_PREVIOUS_CONTAINER, "nginx-proxy-manager"]).await?;
+    anyhow::ensure!(
+        renamed.status.success(),
+        "cannot restore previous NPM container name"
+    );
+    let started = podman_control(&["start", "nginx-proxy-manager"]).await?;
+    anyhow::ensure!(
+        started.status.success(),
+        "previous NPM container restored but failed to start"
+    );
+    Ok(())
+}
+
+async fn repair_legacy_nginx_proxy_manager() -> Result<()> {
+    let previous = podman_control(&["container", "exists", NPM_PREVIOUS_CONTAINER]).await?;
+    anyhow::ensure!(previous.status.code() == Some(1),
+        "NPM previous-container slot is occupied or cannot be inspected; preserve it and review interrupted repair before proceeding");
+    let inspection = podman_control(&[
+        "inspect",
+        "nginx-proxy-manager",
+        "--format",
+        "{{json .Config.Env}}",
+    ])
+    .await?;
+    anyhow::ensure!(
+        inspection.status.success(),
+        "cannot preserve NPM environment before repair"
+    );
+    let environment: Vec<String> =
+        serde_json::from_slice(&inspection.stdout).context("invalid original NPM environment")?;
+    let environment = npm_repair_environment(&environment)?;
+    let storage = crate::container::npm::resolve_storage().await?;
+    let mut manifest: archipelago_container::AppManifest = serde_yaml::from_str(include_str!(
+        "../../../../../../apps/nginx-proxy-manager/manifest.yml"
+    ))?;
+    storage.apply(&mut manifest)?;
+    let stopped = podman_control(&["stop", "--time", "30", "nginx-proxy-manager"]).await?;
+    anyhow::ensure!(
+        stopped.status.success(),
+        "could not stop NPM for a consistent backup"
+    );
+    if let Err(error) = crate::container::migration_backup::snapshot(
+        &manifest,
+        std::path::Path::new("/var/lib/archipelago"),
+        None,
     )
-    .await;
-    let _ = podman_control(&["rm", "-f", "nginx-proxy-manager"]).await;
-    cleanup_nginx_proxy_manager_ports().await;
-    if let Err(err) = recreate_nginx_proxy_manager_container().await {
-        tracing::warn!(error = %err, "failed to recreate stale nginx-proxy-manager container");
+    .await
+    {
+        let _ = podman_control(&["start", "nginx-proxy-manager"]).await;
+        return Err(error);
     }
+    // Keep the original runtime definition for rollback, including its operator
+    // options. Never delete it before the replacement has become ready.
+    let renamed = podman_control(&["rename", "nginx-proxy-manager", NPM_PREVIOUS_CONTAINER]).await;
+    if !renamed.as_ref().is_ok_and(|out| out.status.success()) {
+        let _ = podman_control(&["start", "nginx-proxy-manager"]).await;
+        anyhow::bail!("could not retain legacy NPM runtime; state backup preserved, inspect both container names before retrying");
+    }
+    let replacement = async {
+        recreate_nginx_proxy_manager_container(&storage, &environment).await?;
+        anyhow::ensure!(
+            wait_for_runtime_host_port("nginx-proxy-manager", 8081, 180).await,
+            "replacement NPM admin listener did not become ready"
+        );
+        Ok::<_, anyhow::Error>(())
     }
-
-async fn repair_nginx_proxy_manager_dirs() {
-    let _ = tokio::process::Command::new("sudo")
-        .args([
-            "mkdir",
-            "-p",
-            "/var/lib/archipelago/nginx-proxy-manager/data/letsencrypt-acme-challenge/.well-known/acme-challenge",
-            "/var/lib/archipelago/nginx-proxy-manager/letsencrypt",
-        ])
-        .output()
-        .await;
-    let _ = tokio::process::Command::new("sudo")
-        .args([
-            "chown",
-            "-R",
-            "1000:1000",
-            "/var/lib/archipelago/nginx-proxy-manager",
-        ])
-        .output()
     .await;
+    if let Err(error) = replacement {
+        restore_failed_npm_repair()
+            .await
+            .context("restoring previous NPM after replacement failure")?;
+        return Err(error);
+    }
+    let removed = podman_control(&["rm", NPM_PREVIOUS_CONTAINER]).await?;
+    anyhow::ensure!(
+        removed.status.success(),
+        "replacement ready but previous NPM cleanup failed; rollback container retained"
+    );
+    Ok(())
 }
 
 async fn nginx_proxy_manager_has_legacy_admin_port() -> bool {
@@ -1647,36 +1762,75 @@ async fn nginx_proxy_manager_has_legacy_admin_port() -> bool {
     ports.contains(":81->81/tcp") || ports.contains(":8443->443/tcp")
 }
 
-async fn recreate_nginx_proxy_manager_container() -> Result<()> {
-    tokio::process::Command::new("sudo")
-        .args([
-            "mkdir",
-            "-p",
-            "/var/lib/archipelago/nginx-proxy-manager/data/letsencrypt-acme-challenge/.well-known/acme-challenge",
-            "/var/lib/archipelago/nginx-proxy-manager/letsencrypt",
-        ])
-        .output()
-        .await
-        .context("failed to create nginx-proxy-manager data directories")?;
-    let _ = tokio::process::Command::new("sudo")
-        .args([
-            "chown",
-            "-R",
-            "1000:1000",
-            "/var/lib/archipelago/nginx-proxy-manager",
-        ])
-        .output()
-        .await;
+fn npm_repair_environment(values: &[String]) -> Result<Vec<(String, String)>> {
+    values.iter().map(|value| {
+        let (key, value) = value.split_once('=').context("invalid NPM environment entry")?;
+        anyhow::ensure!(!key.is_empty() && key.chars().all(|c| c.is_ascii_alphanumeric() || c == '_'),
+            "unsupported NPM environment name; original container preserved");
+        anyhow::ensure!(!value.contains(['\n', '\r', '\0']),
+            "NPM environment requires explicit migration of a multiline value; original container preserved");
+        Ok((key.to_owned(), value.to_owned()))
+    }).collect()
+}
 
-    let image = crate::container::image_versions::pinned_image_for_app("nginx-proxy-manager")
-        .unwrap_or_else(|| "docker.io/jc21/nginx-proxy-manager:latest".to_string());
+struct NpmRepairEnvironmentFile(std::path::PathBuf);
+
+impl NpmRepairEnvironmentFile {
+    fn create(environment: &[(String, String)]) -> Result<Self> {
+        use std::io::Write;
+        use std::os::unix::fs::OpenOptionsExt;
+        let path = std::env::temp_dir().join(format!(".archy-npm-env-{}", uuid::Uuid::new_v4()));
+        let mut file = std::fs::OpenOptions::new()
+            .write(true)
+            .create_new(true)
+            .mode(0o600)
+            .open(&path)?;
+        let guard = Self(path);
+        for (key, value) in environment {
+            writeln!(file, "{key}={value}")?;
+        }
+        file.sync_all()?;
+        Ok(guard)
+    }
+}
+
+impl Drop for NpmRepairEnvironmentFile {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_file(&self.0);
+    }
+}
+
+async fn recreate_nginx_proxy_manager_container(
+    storage: &crate::container::npm::Storage,
+    environment: &[(String, String)],
+) -> Result<()> {
+    // Existing directories and ownership came from the active runtime. Never
+    // create a second database tree or recursively rewrite data permissions.
+    for directory in [&storage.data, &storage.certificates] {
+        anyhow::ensure!(
+            std::path::Path::new(directory).is_dir(),
+            "NPM persistent directory is missing"
+        );
+    }
+
+    // This repair changes connectivity, not NPM's application version. Keep
+    // the exact old image so rollback never starts an older binary against a
+    // database that an incidental mutable-tag update may have migrated.
+    let image_output =
+        podman_control(&["inspect", NPM_PREVIOUS_CONTAINER, "--format", "{{.Image}}"]).await?;
+    anyhow::ensure!(
+        image_output.status.success(),
+        "cannot resolve original NPM image for repair"
+    );
+    let image = String::from_utf8(image_output.stdout)?.trim().to_string();
+    anyhow::ensure!(!image.is_empty(), "original NPM image is missing");
     let mut args = vec![
         "run".to_string(),
         "-d".to_string(),
         "--name".to_string(),
         "nginx-proxy-manager".to_string(),
         "--restart=unless-stopped".to_string(),
-        "--network=slirp4netns:allow_host_loopback=true".to_string(),
+        "--network=slirp4netns:allow_host_loopback=true,cidr=169.254.1.0/24".to_string(),
         "--cap-drop=ALL".to_string(),
         "--security-opt=no-new-privileges:true".to_string(),
         "--pids-limit=4096".to_string(),
@@ -1684,24 +1838,32 @@ async fn recreate_nginx_proxy_manager_container() -> Result<()> {
     args.extend(get_app_capabilities("nginx-proxy-manager"));
     args.extend([
         "-p".to_string(),
-        "8081:81".to_string(),
+        "127.0.0.1:8081:81".to_string(),
         "-p".to_string(),
-        "8084:80".to_string(),
+        "127.0.0.1:8088:80".to_string(),
         "-p".to_string(),
-        "8444:443".to_string(),
+        "127.0.0.1:8444:443".to_string(),
         "-v".to_string(),
-        "/var/lib/archipelago/nginx-proxy-manager/data:/data".to_string(),
+        format!("{}:/data", storage.data),
         "-v".to_string(),
-        "/var/lib/archipelago/nginx-proxy-manager/letsencrypt:/etc/letsencrypt".to_string(),
+        format!("{}:/etc/letsencrypt", storage.certificates),
         "--memory".to_string(),
         get_memory_limit("nginx-proxy-manager").to_string(),
         "--cpus=2".to_string(),
     ]);
     args.extend(get_health_check_args("nginx-proxy-manager", ""));
+    // Keep values out of argv/logs AND out of Podman's host environment
+    // (a container's PATH or LD_PRELOAD must never alter the host command).
+    let env_file = NpmRepairEnvironmentFile::create(environment)?;
+    args.extend([
+        "--env-file".to_string(),
+        env_file.0.to_string_lossy().into_owned(),
+    ]);
     args.push(image);
 
-    let refs = args.iter().map(String::as_str).collect::<Vec<_>>();
-    let output = podman_control(&refs).await?;
+    let mut command = tokio::process::Command::new("podman");
+    command.args(&args);
+    let output = command_with_timeout(command, Duration::from_secs(120), "NPM replacement").await?;
     if !output.status.success() {
         anyhow::bail!(
             "podman run nginx-proxy-manager failed: {}",
@@ -1769,7 +1931,7 @@ fn runtime_host_ports(container_name: &str) -> Vec<u16> {
         "vaultwarden" => vec![8082],
         "gitea" => vec![3001, 2222, 3000],
         "nextcloud" => vec![8085],
-        "nginx-proxy-manager" => vec![8081, 8084, 8444],
+        "nginx-proxy-manager" => vec![8081, 8088, 8444],
         _ => Vec::new(),
     };
     ports
@@ -1780,7 +1942,7 @@ fn with_legacy_extra_ports(container_name: &str, mut ports: Vec<u16>) -> Vec<u16
         ports.push(3000);
     }
     if container_name == "nginx-proxy-manager" {
-        for port in [8084, 8444] {
+        for port in [8088, 8444] {
             if !ports.contains(&port) {
                 ports.push(port);
             }
@@ -1812,6 +1974,9 @@ fn manifest_host_ports(container_name: &str) -> Vec<u16> {
 
 pub(super) fn manifest_apps_dirs() -> Vec<std::path::PathBuf> {
     let mut dirs = Vec::new();
+    if let Some(root) = std::env::var_os("ARCHIPELAGO_APPS_DIR") {
+        dirs.push(root.into());
+    }
     if let Ok(manifest_dir) = std::env::var("CARGO_MANIFEST_DIR") {
         dirs.push(Path::new(&manifest_dir).join("../../apps"));
     }
@@ -1842,6 +2007,7 @@ async fn wait_for_runtime_host_port(container_name: &str, port: u16, timeout_sec
     loop {
         let ready = match container_name {
             "uptime-kuma" => http_host_port_ready(port, "/").await,
+            "nginx-proxy-manager" => http_host_port_ready(port, "/api/").await,
             _ => tokio::net::TcpStream::connect(("127.0.0.1", port))
                 .await
                 .is_ok(),
@@ -2032,51 +2198,10 @@ async fn cleanup_start_conflict(container_name: &str, stderr: &str) {
         return;
     }
 
-    let ports = runtime_host_ports(container_name);
-    if !ports.is_empty() {
-        cleanup_ports(&ports).await;
-        return;
-    }
-}
-
-async fn cleanup_runtime_host_ports(container_name: &str) {
-    let ports = runtime_host_ports(container_name);
-    if !ports.is_empty() {
-        cleanup_ports(&ports).await;
-    }
-}
-
-async fn cleanup_nginx_proxy_manager_ports() {
-    cleanup_ports(&[8081, 8084, 8444]).await;
-}
-
-async fn cleanup_ports(ports: &[u16]) {
-    for port in ports {
-        cleanup_stale_pasta_port(&port.to_string()).await;
-    }
-}
-
-async fn cleanup_stale_pasta_port(port: &str) {
-    let kill_listener = format!(
-        "ss -ltnp 'sport = :{}' 2>/dev/null | sed -n 's/.*pid=\\([0-9]*\\).*/\\1/p' | xargs -r kill 2>/dev/null || true",
-        port
-    );
-    let _ = tokio::process::Command::new("sh")
-        .args(["-c", &kill_listener])
-        .output()
-        .await;
-
-    let pattern = format!("pasta.*{}", port);
-    let _ = tokio::process::Command::new("pkill")
-        .args(["-f", &pattern])
-        .output()
-        .await;
-    let pattern = format!("rootlessport.*{}", port);
-    let _ = tokio::process::Command::new("pkill")
-        .args(["-f", &pattern])
-        .output()
-        .await;
-    tokio::time::sleep(std::time::Duration::from_secs(1)).await;
+    // Only reap processes proven to belong to an absent container. The app
+    // gate shares the app's port on other addresses and lives in this daemon;
+    // killing port owners (or matching argv with pkill) kills the dashboard.
+    crate::container::ghost_reaper::reap_for_app(container_name).await;
 }
 
 pub(super) fn is_missing_companion_ok(name: &str, stderr: &str) -> bool {
@@ -2095,13 +2220,16 @@ async fn flip_package_state(
     package_id: &str,
     transitional: PackageState,
 ) -> Option<PackageState> {
-    let (mut data, _) = state_manager.get_snapshot().await;
+    state_manager
+        .mutate_data(|data| {
             let prev = data.package_data.get(package_id).map(|e| e.state.clone());
             if let Some(entry) = data.package_data.get_mut(package_id) {
+                entry.ui_ready = Some(false);
                 entry.state = transitional;
-        state_manager.update_data(data).await;
             }
             prev
+        })
+        .await
 }
 
 /// Write the package entry's final state. No-op if the entry has since
@@ -2111,13 +2239,18 @@ async fn set_package_state(
     package_id: &str,
     new_state: PackageState,
 ) {
-    let (mut data, _) = state_manager.get_snapshot().await;
+    state_manager
+        .mutate_data(|data| {
             if let Some(entry) = data.package_data.get_mut(package_id) {
                 if entry.state != new_state {
+                    if new_state != PackageState::Running {
+                        entry.ui_ready = Some(false);
+                    }
                     entry.state = new_state;
-            state_manager.update_data(data).await;
                 }
             }
+        })
+        .await
 }
 
 pub(super) async fn reconcile_companions_for(package_id: &str) {
@@ -2183,8 +2316,54 @@ pub(super) fn orchestrator_uninstall_app_ids(package_id: &str) -> Vec<String> {
 
 #[cfg(test)]
 mod tests {
+    #[test]
+    fn npm_environment_backup_is_private_exact_and_removed_on_drop() {
+        use std::os::unix::fs::PermissionsExt;
+        let values = vec![
+            "DB_PASSWORD=fixture=a b".to_string(),
+            "PATH=/container/only".to_string(),
+        ];
+        let parsed = super::npm_repair_environment(&values).unwrap();
+        let host_path = std::env::var_os("PATH");
+        let path = {
+            let file = super::NpmRepairEnvironmentFile::create(&parsed).unwrap();
+            assert_eq!(
+                std::fs::metadata(&file.0).unwrap().permissions().mode() & 0o777,
+                0o600
+            );
+            assert_eq!(
+                std::fs::read_to_string(&file.0).unwrap(),
+                "DB_PASSWORD=fixture=a b\nPATH=/container/only\n"
+            );
+            assert_eq!(std::env::var_os("PATH"), host_path);
+            file.0.clone()
+        };
+        assert!(!path.exists());
+        for value in [
+            "INVALID",
+            "=empty key",
+            "KEY=value\nINJECTED=true",
+            "--env=value",
+        ] {
+            assert!(super::npm_repair_environment(&[value.to_string()]).is_err());
+        }
+    }
     use super::*;
 
+    #[tokio::test]
+    async fn port_conflict_cleanup_preserves_live_host_listener() {
+        // The previous ss|kill sweep terminated the daemon's app gate on a
+        // restart. Keep a real listening socket owned by this test process.
+        let listener = tokio::net::TcpListener::bind("127.0.0.2:2342")
+            .await
+            .unwrap();
+        let addr = listener.local_addr().unwrap();
+        cleanup_start_conflict("photoprism", "address already in use").await;
+        let client = tokio::net::TcpStream::connect(addr).await.unwrap();
+        let _connection = listener.accept().await.unwrap();
+        drop(client);
+    }
+
     #[test]
     fn missing_container_classifier_covers_podman5_phrasings() {
         // Regression (.228 gate 2026-07-08): podman 5.x `inspect` on a missing

core/archipelago/src/api/rpc/package/set_config.rs

@@ -153,8 +153,18 @@ impl RpcHandler {
         let default = app_catalog::catalog_default_version(app_id);
         let cfg = version_config::read(app_id);
         let installed = installed_version(app_id).await;
+        let bitcoin_prune = if matches!(app_id, "bitcoin-core" | "bitcoin-knots") {
+            Some(
+                crate::settings::bitcoin_storage::load(&self.config.data_dir)
+                    .await?
+                    .prune,
+            )
+        } else {
+            None
+        };
 
         Ok(serde_json::json!({
+            "bitcoinPrune": bitcoin_prune,
             "id": app_id,
             "supportsVersions": supports_versions(app_id),
             "default": default,

core/archipelago/src/api/rpc/package/update.rs

@@ -4,22 +4,22 @@
 //! remove old container(s) → recreate (orchestrator-first, legacy fallback) → verify running.
 //! Data volumes are preserved (bind mounts, not stored in container).
 
-use super::config::get_containers_for_app;
+use super::config::{all_container_names, get_containers_for_app};
 use super::install::install_log;
 use super::progress::parse_pull_progress;
-use super::runtime::stop_timeout_secs;
 use super::validation::validate_app_id;
 use crate::api::rpc::RpcHandler;
 use crate::container::image_versions;
 use crate::data_model::{InstallPhase, PackageState};
 use anyhow::{Context, Result};
+use std::{collections::HashSet, path::Path};
 use tokio::io::{AsyncBufReadExt, BufReader};
 use tracing::{error, info, warn};
 
 const PODMAN_UPDATE_PULL_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(600);
 
 impl RpcHandler {
-    /// Update a package to the version pinned in image-versions.sh.
+    /// Update a package to the freshly verified catalog target.
     /// This is a manual operation — the user clicks "Update" in the UI.
     pub(in crate::api::rpc) async fn handle_package_update(
         &self,
@@ -31,6 +31,24 @@ impl RpcHandler {
             .and_then(|v| v.as_str())
             .ok_or_else(|| anyhow::anyhow!("Missing package id"))?;
         validate_app_id(package_id)?;
+        let lifecycle_guard =
+            crate::container::update_transaction::Guard::acquire(&self.config.data_dir)?;
+        lifecycle_guard.require_clear()?;
+
+        // An Update click must not act on an hourly cache that predates the
+        // button. Fetch and verify first; failure leaves running containers alone.
+        crate::container::app_catalog::refresh_catalog(&self.config.data_dir)
+            .await
+            .context(
+                "Cannot check the signed app catalog; update cancelled before changing containers",
+            )?;
+        if let Some(orch) = &self.orchestrator {
+            // Reload even when bytes did not change: a previous reload may have
+            // failed after the cache was written, or another refresher wrote it.
+            orch.reload_manifests()
+                .await
+                .context("Cannot load current app manifests; update cancelled")?;
+        }
 
         // Resolve the target image. Prefer the remote app catalog (decoupled
         // from the binary OTA), falling back to the image-versions.sh pin. This
@@ -42,6 +60,37 @@ impl RpcHandler {
         let pinned = crate::container::app_catalog::catalog_primary_image(package_id)
             .or_else(|| image_versions::pinned_image_for_app(package_id));
 
+        let targets = pinned
+            .as_ref()
+            .map(|target| self.resolve_images_to_pull(package_id, target));
+        // A stopped Quadlet normally removes its --rm container. Absence is
+        // not an install decision: only a known single managed app with durable
+        // installed AND stopped evidence may enter the recreate path.
+        let known_managed =
+            if should_try_orchestrator_update(package_id, self.orchestrator.is_some()) {
+                self.orchestrator
+                    .as_ref()
+                    .expect("orchestrator presence checked")
+                    .knows_app(orchestrator_update_app_id(package_id))
+                    .await
+            } else {
+                false
+            };
+        let markers = UpdateMarkers::load(&self.config.data_dir, package_id).await?;
+        let installed = inspect_update_images(package_id).await?;
+        validate_update_presence(package_id, known_managed, !installed.is_empty(), &markers)?;
+        if let Some(targets) = &targets {
+            if !update_targets_need_change(targets, &installed)? && !markers.stopped {
+                install_log(&format!(
+                    "UPDATE SKIP: {} — target versions already installed",
+                    package_id
+                ))
+                .await;
+                self.clear_install_progress(package_id).await;
+                return Ok(serde_json::json!({"status": "up-to-date", "package_id": package_id}));
+            }
+        }
+
         // Note: the `already updating` guard lives in `spawn_package_update`
         // (the async wrapper that dispatch actually routes to). By the time
         // this inner function runs, the wrapper has already flipped state to
@@ -80,6 +129,25 @@ impl RpcHandler {
             if let Some(orchestrator) = self.orchestrator.as_ref() {
                 match orchestrator.upgrade(orchestrator_app_id).await {
                     Ok(()) => {
+                        if let Some(image) = orchestrator
+                            .staged_upgrade_image(orchestrator_app_id)
+                            .await?
+                        {
+                            // The orchestrator proved the pinned image exists and
+                            // persisted its reviewed manifest. No running container
+                            // or healthy service is claimed for a stopped update.
+                            self.clear_install_progress(package_id).await;
+                            return Ok(serde_json::json!({
+                                "status": "staged", "state": "stopped",
+                                "package_id": package_id, "image": image,
+                            }));
+                        }
+                        if let Some(targets) = &targets {
+                            verify_update_targets(
+                                targets,
+                                &inspect_update_images(package_id).await?,
+                            )?;
+                        }
                         self.set_install_phase(package_id, InstallPhase::WaitingHealthy)
                             .await;
                         if let Ok(health) = orchestrator.health(orchestrator_app_id).await {
@@ -133,18 +201,50 @@ impl RpcHandler {
         };
 
         // Resolve images to pull — either a stack or single container
-        let images_to_pull = self.resolve_images_to_pull(package_id, &pinned);
+        let images_to_pull =
+            targets.unwrap_or_else(|| self.resolve_images_to_pull(package_id, &pinned));
 
-        // Get all containers for this app
+        // Managed imports are intentionally private. Resolve the trusted catalog
+        // against the reviewed local digest plan before any registry preparation;
+        // never pull mutable dependency tags over an approved local plan. Every
+        // preparation refusal clears Updating, including inventory/plan failures.
+        let preparation = async {
             let containers = get_containers_for_app(package_id).await?;
-        if containers.is_empty() {
-            self.clear_update_state(package_id).await;
-            return Err(anyhow::anyhow!("No containers found for {}", package_id));
+            anyhow::ensure!(
+                !containers.is_empty(),
+                "No containers found for {}",
+                package_id
+            );
+            let images = self
+                .reviewed_managed_image_references(
+                    package_id,
+                    &containers,
+                    &images_to_pull,
+                    &lifecycle_guard,
+                )
+                .await?;
+            Ok::<_, anyhow::Error>((containers, images))
         }
+        .await;
+        let (containers, images_to_pull) = match preparation {
+            Ok(prepared) => prepared,
+            Err(error) => {
+                self.clear_install_progress(package_id).await;
+                self.clear_update_state(package_id).await;
+                return Err(error);
+            }
+        };
 
-        // Execute update — on failure, attempt rollback by restarting old containers
-        match self
-            .execute_update(package_id, &containers, &images_to_pull)
+        // Resolve every image while the old stack is still available. A
+        // registry outage or missing private import must not stop the app or
+        // enter rollback (which could start a deliberately stopped member).
+        self.set_install_phase(package_id, InstallPhase::PullingImage)
+            .await;
+        match preflighted_stack_update(
+            &images_to_pull,
+            |image| async move { self.pull_update_image(package_id, &image).await },
+            || self.execute_update(package_id, &containers, &images_to_pull, &lifecycle_guard),
+        )
         .await
         {
             Ok(()) => {
@@ -155,17 +255,26 @@ impl RpcHandler {
                     "package_id": package_id,
                 }))
             }
-            Err(e) => {
+            Err(UpdateFailure::Preparation(error)) => {
+                self.clear_install_progress(package_id).await;
+                self.clear_update_state(package_id).await;
+                Err(error)
+            }
+            Err(UpdateFailure::Execution(e)) => {
                 error!("Update {} failed: {}. Attempting rollback.", package_id, e);
                 install_log(&format!(
                     "UPDATE FAIL: {} — {}. Rolling back.",
                     package_id, e
                 ))
                 .await;
-                self.rollback_update(package_id, &containers).await;
+                // Transaction executor already recovered original identities or
+                // returned an explicit unresolved state. Never guess/reinstall.
                 self.clear_install_progress(package_id).await;
                 self.clear_update_state(package_id).await;
-                Err(e.context(format!("Update {} failed, rolled back", package_id)))
+                Err(e.context(format!(
+                    "Update {} failed; see retained-runtime recovery result",
+                    package_id
+                )))
             }
         }
     }
@@ -210,130 +319,110 @@ impl RpcHandler {
         }
     }
 
-    /// Core update execution: stop → pull → remove → recreate → verify.
+    /// Images are prepared first. The transaction preserves original identities,
+    /// creates stopped replacements, and restores the exact old states on failure.
     async fn execute_update(
         &self,
         package_id: &str,
         containers: &[String],
         images_to_pull: &[(String, String)],
+        guard: &crate::container::update_transaction::Guard,
     ) -> Result<()> {
-        // Phase: Preparing — about to stop the running container(s) so
-        // we can swap images. Fast.
+        use crate::container::update_transaction::{self, Podman};
+        let mut supervised = 0;
+        for name in containers {
+            if crate::container::quadlet::unit_exists(name).await {
+                supervised += 1;
+            }
+        }
+        anyhow::ensure!(
+            supervised == 0 || supervised == containers.len(),
+            "Mixed managed/unmanaged stack requires an explicit recovery plan; originals unchanged"
+        );
+        let managed = supervised != 0;
+        anyhow::ensure!(
+            !managed || package_id == "indeedhub",
+            "This managed app has no qualified maintenance controller; originals unchanged"
+        );
+        let targets = Podman::targets(images_to_pull, !managed).await?;
+        let names: HashSet<_> = containers.iter().map(String::as_str).collect();
+        anyhow::ensure!(
+            targets.len() == names.len()
+                && targets
+                    .iter()
+                    .all(|target| names.contains(target.name.as_str())),
+            "Update target membership differs from installed stack; no containers changed"
+        );
         self.set_install_phase(package_id, InstallPhase::Preparing)
             .await;
-
-        // 1. Graceful stop all containers (reverse order for dependencies)
-        info!(
-            "Update {}: stopping {} containers",
-            package_id,
-            containers.len()
-        );
-        for name in containers.iter().rev() {
-            let timeout = stop_timeout_secs(name);
-            info!(
-                "Update {}: stopping {} (timeout: {}s)",
-                package_id, name, timeout
-            );
-            let out = tokio::process::Command::new("podman")
-                .args(["stop", "-t", timeout, name])
-                .output()
+        if managed {
+            use crate::container::supervised_runtime::{
+                load_reviewed_plans, LegacyIndeeMaintenance, SystemdSupervisor,
+            };
+            let plans = load_reviewed_plans(&self.config.data_dir, package_id)?;
+            let adapter = SystemdSupervisor::new(
+                self.config.data_dir.clone(),
+                plans,
+                LegacyIndeeMaintenance::new(guard)?,
+            )
+            .await?;
+            let targets = adapter.reviewed_targets(&targets).await?;
+            crate::container::supervised_update::execute(guard, package_id, &targets, &adapter)
                 .await
-                .context(format!("Failed to stop {}", name))?;
-            if !out.status.success() {
-                let stderr = String::from_utf8_lossy(&out.stderr);
-                warn!(
-                    "Update {}: stop {} failed: {}",
-                    package_id,
-                    name,
-                    stderr.trim()
-                );
-                // Continue — container might already be stopped
+        } else {
+            update_transaction::execute(guard, package_id, &targets, &Podman).await
         }
     }
 
-        // Phase: PullingImage — about to fetch each pinned image in turn.
-        self.set_install_phase(package_id, InstallPhase::PullingImage)
-            .await;
-
-        // 2. Pull new images with progress
-        info!(
-            "Update {}: pulling {} images",
-            package_id,
-            images_to_pull.len()
-        );
-        for (i, (name, image)) in images_to_pull.iter().enumerate() {
-            info!(
-                "Update {}: pulling image {}/{} ({})",
-                package_id,
-                i + 1,
-                images_to_pull.len(),
-                image
-            );
-            self.pull_update_image(package_id, image)
-                .await
-                .context(format!("Failed to pull {} for {}", image, name))?;
-        }
-
-        // 3. Remove old containers
-        info!("Update {}: removing old containers", package_id);
+    async fn reviewed_managed_image_references(
+        &self,
+        package_id: &str,
+        containers: &[String],
+        images: &[(String, String)],
+        guard: &crate::container::update_transaction::Guard,
+    ) -> Result<Vec<(String, String)>> {
+        use crate::container::supervised_runtime::{
+            load_reviewed_plans, LegacyIndeeMaintenance, SystemdSupervisor,
+        };
+        use crate::container::supervised_update::Supervisor;
+        use crate::container::update_transaction::Podman;
+        let mut managed = 0;
         for name in containers {
-            let out = tokio::process::Command::new("podman")
-                .args(["rm", name])
-                .output()
-                .await
-                .context(format!("Failed to remove {}", name))?;
-            if !out.status.success() {
-                let stderr = String::from_utf8_lossy(&out.stderr);
-                // Force remove as fallback
-                warn!(
-                    "Update {}: rm {} failed ({}), forcing",
-                    package_id,
-                    name,
-                    stderr.trim()
+            if crate::container::quadlet::unit_exists(name).await {
+                managed += 1;
+            }
+        }
+        if managed == 0 {
+            return Ok(images.to_vec());
+        }
+        anyhow::ensure!(
+            managed == containers.len() && package_id == "indeedhub",
+            "Managed stack requires its complete qualified maintenance plan; originals unchanged"
         );
-                let _ = tokio::process::Command::new("podman")
-                    .args(["rm", "-f", name])
-                    .output()
-                    .await;
-            }
-        }
-
-        // Phase: CreatingContainer — about to recreate each container.
-        self.set_install_phase(package_id, InstallPhase::CreatingContainer)
-            .await;
-
-        // 4. Recreate containers (orchestrator-first, reconcile fallback)
-        info!("Update {}: recreating containers", package_id);
-        for name in containers {
-            self.recreate_container_for_update(package_id, name).await?;
-            // Brief delay between containers for dependency initialization
-            tokio::time::sleep(std::time::Duration::from_secs(2)).await;
-        }
-
-        // Phase: WaitingHealthy — reconcile has started every container,
-        // now verifying each reached running state.
-        self.set_install_phase(package_id, InstallPhase::WaitingHealthy)
-            .await;
-
-        // 5. Verify containers reached running state
-        tokio::time::sleep(std::time::Duration::from_secs(5)).await;
-        for name in containers {
-            let status = tokio::process::Command::new("podman")
-                .args(["inspect", name, "--format", "{{.State.Status}}"])
-                .output()
-                .await;
-            if let Ok(o) = status {
-                let state = String::from_utf8_lossy(&o.stdout).trim().to_string();
-                if state == "exited" {
-                    warn!(
-                        "Update {}: container {} exited after recreate",
-                        package_id, name
+        let catalog = Podman::targets(images, false).await?;
+        let names: HashSet<_> = containers.iter().map(String::as_str).collect();
+        anyhow::ensure!(
+            catalog.len() == names.len()
+                && catalog
+                    .iter()
+                    .all(|target| names.contains(target.name.as_str())),
+            "Reviewed managed target membership differs from installed stack"
         );
+        let adapter = SystemdSupervisor::new(
+            self.config.data_dir.clone(),
+            load_reviewed_plans(&self.config.data_dir, package_id)?,
+            LegacyIndeeMaintenance::new(guard)?,
+        )
+        .await?;
+        let targets = adapter.reviewed_targets(&catalog).await?;
+        for target in &targets {
+            let original = adapter.capture(&target.name).await?;
+            adapter.prepare_target(target, &original).await?;
         }
-            }
-        }
-
-        Ok(())
+        Ok(targets
+            .into_iter()
+            .map(|target| (target.name, target.reference))
+            .collect())
     }
 
     async fn recreate_container_for_update(
@@ -385,6 +474,32 @@ impl RpcHandler {
     async fn pull_update_image(&self, package_id: &str, image: &str) -> Result<()> {
         self.set_install_progress(package_id, 0, 0).await;
 
+        if immutable_update_image(image) {
+            // A digest-addressed lookup asks Podman for these exact bytes,
+            // unlike a mutable tag lookup. Private imports need no registry.
+            let local = tokio::time::timeout(
+                std::time::Duration::from_secs(30),
+                tokio::process::Command::new("podman")
+                    .args(["image", "exists", image])
+                    .kill_on_drop(true)
+                    .output(),
+            )
+            .await
+            .context("Local image lookup timed out; existing app remains unchanged")??;
+            match local.status.code() {
+                Some(0) => {
+                    self.set_install_progress(package_id, 100, 100).await;
+                    return Ok(());
+                }
+                Some(1) => {}
+                _ => anyhow::bail!("Cannot inspect local image storage; update cancelled"),
+            }
+        }
+        anyhow::ensure!(
+            !image.starts_with("localhost/"),
+            "The exact private image must be imported before updating this app"
+        );
+
         let mut cmd = tokio::process::Command::new("podman");
         cmd.arg("pull");
         if archipelago_container::image_uses_insecure_registry(image) {
@@ -466,58 +581,213 @@ impl RpcHandler {
         stack_images
     }
 
-    /// Rollback: restart old containers if they still exist.
-    /// Called when update fails partway through.
-    async fn rollback_update(&self, package_id: &str, containers: &[String]) {
-        warn!("Rolling back update for {}", package_id);
-        for name in containers {
-            // Try to start — works if container still exists (wasn't removed yet)
-            let out = tokio::process::Command::new("podman")
-                .args(["start", name])
-                .output()
-                .await;
-            match out {
-                Ok(o) if o.status.success() => {
-                    info!("Rollback: restarted {}", name);
-                }
-                Ok(o) => {
-                    let stderr = String::from_utf8_lossy(&o.stderr);
-                    warn!("Rollback: could not restart {}: {}", name, stderr.trim());
-                    // Container was already removed (forward path ran `podman rm`).
-                    // Recreate via orchestrator-first path with legacy fallback.
-                    if let Err(recreate_err) =
-                        self.recreate_container_for_update(package_id, name).await
-                    {
-                        error!(
-                            "Rollback: failed to recreate {} during rollback of {}: {}",
-                            name, package_id, recreate_err
-                        );
-                    }
-                }
-                Err(e) => {
-                    error!("Rollback: failed to restart {}: {}", name, e);
-                }
-            }
-        }
-    }
-
     /// Clear the Updating state (used on failure/rollback).
     async fn clear_update_state(&self, package_id: &str) {
         let (mut data, _) = self.state_manager.get_snapshot().await;
         if let Some(entry) = data.package_data.get_mut(package_id) {
             // Don't overwrite state from scanner — just clear if still Updating
             if entry.state == PackageState::Updating {
-                entry.state = PackageState::Stopped;
+                // Unknown is not stopped: the authoritative scanner will
+                // refresh actual retained runtime immediately in the wrapper.
+                entry.state = PackageState::Installed;
             }
         }
         self.state_manager.update_data(data).await;
     }
 }
 
+#[derive(Default)]
+struct UpdateMarkers {
+    installed: bool,
+    stopped: bool,
+    uninstalled: bool,
+}
+
+impl UpdateMarkers {
+    async fn load(data_dir: &Path, package_id: &str) -> Result<Self> {
+        let mut names = all_container_names(package_id);
+        names.push(package_id.to_string());
+        names.push(orchestrator_update_app_id(package_id).to_string());
+        let installed = read_update_markers(data_dir, "installed-apps.json").await?;
+        let stopped = read_update_markers(data_dir, "user-stopped.json").await?;
+        let uninstalled = read_update_markers(data_dir, "user-uninstalled.json").await?;
+        Ok(Self {
+            installed: names.iter().any(|name| installed.contains(name)),
+            stopped: names.iter().any(|name| stopped.contains(name)),
+            uninstalled: names.iter().any(|name| uninstalled.contains(name)),
+        })
+    }
+}
+
+// The recovery loaders intentionally return empty on malformed state. An update
+// must instead distinguish unavailable evidence from a proven absence of an
+// uninstall decision before it can recreate a removed Quadlet container.
+async fn read_update_markers(data_dir: &Path, filename: &str) -> Result<HashSet<String>> {
+    match tokio::fs::read(data_dir.join(filename)).await {
+        Ok(bytes) => serde_json::from_slice(&bytes)
+            .with_context(|| format!("Cannot read {filename}; update cancelled")),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(HashSet::new()),
+        Err(error) => {
+            Err(error).with_context(|| format!("Cannot read {filename}; update cancelled"))
+        }
+    }
+}
+
+fn validate_update_presence(
+    package_id: &str,
+    known_managed: bool,
+    has_containers: bool,
+    markers: &UpdateMarkers,
+) -> Result<()> {
+    anyhow::ensure!(
+        !markers.uninstalled,
+        "{} was uninstalled; use an explicit install instead of update",
+        package_id
+    );
+    anyhow::ensure!(
+        has_containers || (known_managed && markers.installed && markers.stopped),
+        "No containers or durable stopped installation found for {}",
+        package_id
+    );
+    Ok(())
+}
+
+async fn inspect_update_images(package_id: &str) -> Result<Vec<(String, String)>> {
+    let containers = get_containers_for_app(package_id).await?;
+    if containers.is_empty() {
+        // The caller decides whether durable installation evidence authorizes
+        // a missing runtime. Never invoke bare `podman inspect` here.
+        return Ok(Vec::new());
+    }
+    let mut command = tokio::process::Command::new("podman");
+    command.arg("inspect").args(&containers).kill_on_drop(true);
+    let output = tokio::time::timeout(std::time::Duration::from_secs(30), command.output())
+        .await
+        .context("Timed out checking installed images")??;
+    anyhow::ensure!(
+        output.status.success(),
+        "Cannot inspect installed images; update cancelled"
+    );
+    let inspected: Vec<serde_json::Value> = serde_json::from_slice(&output.stdout)?;
+    inspected
+        .iter()
+        .map(|entry| {
+            let name = entry
+                .get("Name")
+                .and_then(|v| v.as_str())
+                .ok_or_else(|| anyhow::anyhow!("Container inspection omitted Name"))?;
+            let image = entry
+                .get("ImageName")
+                .and_then(|v| v.as_str())
+                .ok_or_else(|| anyhow::anyhow!("Container inspection omitted ImageName"))?;
+            Ok((name.trim_start_matches('/').to_string(), image.to_string()))
+        })
+        .collect()
+}
+
+fn installed_image_for_target<'a>(
+    app_id: &str,
+    installed: &'a [(String, String)],
+) -> Option<&'a str> {
+    installed
+        .iter()
+        .find(|(name, _)| {
+            candidate_app_ids_for_container(name)
+                .iter()
+                .any(|id| id == app_id)
+        })
+        .map(|(_, image)| image.as_str())
+}
+
+/// A successful recreate is not proof that it used the downloaded image.
+fn verify_update_targets(
+    targets: &[(String, String)],
+    installed: &[(String, String)],
+) -> Result<()> {
+    anyhow::ensure!(!targets.is_empty(), "No update targets resolved");
+    for (app_id, target) in targets {
+        let running = installed_image_for_target(app_id, installed).ok_or_else(|| {
+            anyhow::anyhow!("Update {}: target container missing after recreate", app_id)
+        })?;
+        anyhow::ensure!(
+            image_versions::extract_version_from_image(target)
+                == image_versions::extract_version_from_image(running)
+                || image_versions::compare_image_versions(target, running)
+                    == Some(std::cmp::Ordering::Equal),
+            "Update {}: recreated container did not reach target version {}",
+            app_id,
+            image_versions::extract_version_from_image(target)
+        );
+    }
+    Ok(())
+}
+
+/// Check every stack component, not just the version shown on its tile. A
+/// newer backend must still update when its frontend version is unchanged.
+/// A stale target for any component cancels before pulling or stopping anything.
+fn update_targets_need_change(
+    targets: &[(String, String)],
+    installed: &[(String, String)],
+) -> Result<bool> {
+    use std::cmp::Ordering;
+    anyhow::ensure!(!targets.is_empty(), "No update targets resolved");
+    let mut changed = false;
+    for (app_id, target) in targets {
+        let running = installed_image_for_target(app_id, installed);
+        match running.and_then(|image| image_versions::compare_image_versions(target, image)) {
+            Some(Ordering::Less) => anyhow::bail!(
+                "Catalog target for {} is older than the installed image; refusing downgrade",
+                app_id
+            ),
+            Some(Ordering::Equal) => {}
+            Some(Ordering::Greater) | None => changed = true,
+        }
+    }
+    Ok(changed)
+}
+
 fn should_try_orchestrator_update(package_id: &str, orchestrator_available: bool) -> bool {
     orchestrator_available && !uses_legacy_update_flow(package_id)
 }
 
+fn immutable_update_image(image: &str) -> bool {
+    image.rsplit_once("@sha256:").is_some_and(|(name, digest)| {
+        !name.is_empty()
+            && !name.contains('@')
+            && digest.len() == 64
+            && digest.bytes().all(|byte| byte.is_ascii_hexdigit())
+    })
+}
+
+#[derive(Debug)]
+enum UpdateFailure {
+    Preparation(anyhow::Error),
+    Execution(anyhow::Error),
+}
+
+/// A preparation failure never enters the lifecycle/rollback path. Keep this
+/// sequencing injectable so failed second-image pulls are tested without apps.
+async fn preflighted_stack_update<P, PF, E, EF>(
+    images: &[(String, String)],
+    mut prepare: P,
+    execute: E,
+) -> std::result::Result<(), UpdateFailure>
+where
+    P: FnMut(String) -> PF,
+    PF: std::future::Future<Output = Result<()>>,
+    E: FnOnce() -> EF,
+    EF: std::future::Future<Output = Result<()>>,
+{
+    for (name, image) in images {
+        prepare(image.clone()).await.map_err(|error| {
+            UpdateFailure::Preparation(error.context(format!(
+                "Cannot prepare image for {name}; existing containers were left unchanged"
+            )))
+        })?;
+    }
+    execute().await.map_err(UpdateFailure::Execution)
+}
+
 fn orchestrator_update_app_id(package_id: &str) -> &str {
     match package_id {
         "electrs" | "mempool-electrs" => "electrumx",
@@ -526,7 +796,10 @@ fn orchestrator_update_app_id(package_id: &str) -> &str {
 }
 
 fn uses_legacy_update_flow(package_id: &str) -> bool {
-    matches!(
+    // A primary container already at its target does not mean its backend or
+    // database is current. Route every mapped stack through the component flow.
+    !image_versions::containers_for_stack(package_id).is_empty()
+        || matches!(
             package_id,
             // Multi-container stacks still updated via the stack-aware path.
             "immich" | "penpot" | "penpot-frontend" | "indeedhub"
@@ -554,7 +827,12 @@ fn candidate_app_ids_for_container(container_name: &str) -> Vec<String> {
         "archy-bitcoin-ui" => push("bitcoin-ui"),
         "archy-lnd-ui" => push("lnd-ui"),
         "archy-electrs-ui" => push("electrs-ui"),
-        "mempool" => {
+        "mysql-mempool" => push("archy-mempool-db"),
+        "btcpay" | "btcpayserver" | "archy-btcpay" => push("btcpay-server"),
+        "homeassistant" | "archy-homeassistant" => push("home-assistant"),
+        "fedimintd" => push("fedimint"),
+        "electrs" | "mempool-electrs" => push("electrumx"),
+        "mempool" | "mempool-web" => {
             push("archy-mempool-web");
             push("mempool");
         }
@@ -571,28 +849,261 @@ fn candidate_app_ids_for_container(container_name: &str) -> Vec<String> {
 #[cfg(test)]
 mod tests {
     use super::{
-        candidate_app_ids_for_container, orchestrator_update_app_id,
-        should_try_orchestrator_update, uses_legacy_update_flow,
+        candidate_app_ids_for_container, immutable_update_image, orchestrator_update_app_id,
+        should_try_orchestrator_update, update_targets_need_change, uses_legacy_update_flow,
+        validate_update_presence, verify_update_targets, UpdateMarkers,
     };
 
+    #[tokio::test]
+    async fn stopped_installed_managed_app_updates_after_quadlet_container_disappears() {
+        let root = tempfile::tempdir().unwrap();
+        crate::crash_recovery::mark_installed(root.path(), "node-demo-music").await;
+        crate::crash_recovery::mark_user_stopped(root.path(), "node-demo-music").await;
+        let markers = UpdateMarkers::load(root.path(), "node-demo-music")
+            .await
+            .unwrap();
+        validate_update_presence("node-demo-music", true, false, &markers).unwrap();
+        let target = vec![("node-demo-music".into(), "localhost/music:2".into())];
+        assert!(super::update_targets_need_change(&target, &[]).unwrap());
+        // Success must still prove that upgrade actually created the target.
+        assert!(verify_update_targets(&target, &[]).is_err());
+        assert!(verify_update_targets(&target, &target).is_ok());
+        assert!(crate::crash_recovery::load_user_stopped(root.path())
+            .await
+            .contains("node-demo-music"));
+    }
+
+    #[test]
+    fn absent_catalog_app_or_unmanaged_runtime_is_not_an_update_installation() {
+        for (managed, installed, stopped) in [
+            (true, false, false),
+            (true, false, true),
+            (true, true, false),
+            (false, true, true),
+        ] {
+            let markers = UpdateMarkers {
+                installed,
+                stopped,
+                uninstalled: false,
+            };
+            assert!(validate_update_presence("optional", managed, false, &markers).is_err());
+        }
+        // Existing legacy containers remain updateable without modern markers.
+        assert!(validate_update_presence("legacy", false, true, &UpdateMarkers::default()).is_ok());
+        assert!(super::update_targets_need_change(&[], &[]).is_err());
+        assert!(verify_update_targets(&[], &[]).is_err());
+    }
+
+    #[tokio::test]
+    async fn uninstall_tombstone_beats_stale_installed_and_stopped_markers() {
+        let root = tempfile::tempdir().unwrap();
+        crate::crash_recovery::mark_installed(root.path(), "node-demo-music").await;
+        crate::crash_recovery::mark_user_stopped(root.path(), "node-demo-music").await;
+        crate::crash_recovery::mark_user_uninstalled(root.path(), "archy-node-demo-music").await;
+        let markers = UpdateMarkers::load(root.path(), "node-demo-music")
+            .await
+            .unwrap();
+        for present in [false, true] {
+            assert!(validate_update_presence("node-demo-music", true, present, &markers).is_err());
+        }
+    }
+
+    #[tokio::test]
+    async fn damaged_lifecycle_markers_cannot_authorize_recreation() {
+        let root = tempfile::tempdir().unwrap();
+        let absent = UpdateMarkers::load(root.path(), "optional").await.unwrap();
+        assert!(validate_update_presence("optional", true, false, &absent).is_err());
+        for name in [
+            "installed-apps.json",
+            "user-stopped.json",
+            "user-uninstalled.json",
+        ] {
+            tokio::fs::write(root.path().join(name), b"not-json")
+                .await
+                .unwrap();
+            assert!(UpdateMarkers::load(root.path(), "optional").await.is_err());
+            tokio::fs::remove_file(root.path().join(name))
+                .await
+                .unwrap();
+        }
+    }
+
+    #[test]
+    fn indeehub_update_resolves_every_member_in_dependency_order() {
+        let members = crate::container::image_versions::containers_for_stack("indeedhub");
+        let expected = super::all_container_names("indeedhub");
+        assert_eq!(
+            members.iter().map(|(name, _)| *name).collect::<Vec<_>>(),
+            expected
+        );
+        let source = include_str!(concat!(
+            env!("CARGO_MANIFEST_DIR"),
+            "/../../scripts/image-versions.sh"
+        ));
+        for (_, variable) in members {
+            assert!(
+                source
+                    .lines()
+                    .any(|line| line.starts_with(&format!("{variable}="))),
+                "Missing image pin {variable}"
+            );
+        }
+        assert!(super::uses_legacy_update_flow("indeedhub"));
+    }
+
+    #[tokio::test]
+    async fn stack_image_failure_precedes_every_lifecycle_action() {
+        use std::sync::{Arc, Mutex};
+        for failed_second in [true, false] {
+            let calls = Arc::new(Mutex::new(Vec::new()));
+            let preparing = calls.clone();
+            let executing = calls.clone();
+            let images = vec![
+                ("web".into(), "web-image".into()),
+                ("api".into(), "api-image".into()),
+            ];
+            let result = super::preflighted_stack_update(
+                &images,
+                move |image| {
+                    let preparing = preparing.clone();
+                    async move {
+                        preparing.lock().unwrap().push(format!("prepare:{image}"));
+                        anyhow::ensure!(!(failed_second && image == "api-image"), "import missing");
+                        Ok(())
+                    }
+                },
+                move || async move {
+                    executing.lock().unwrap().extend([
+                        "stop".into(),
+                        "remove".into(),
+                        "start".into(),
+                    ]);
+                    Ok(())
+                },
+            )
+            .await;
+            if failed_second {
+                assert!(matches!(result, Err(super::UpdateFailure::Preparation(_))));
+                assert_eq!(
+                    *calls.lock().unwrap(),
+                    ["prepare:web-image", "prepare:api-image"]
+                );
+            } else {
+                assert!(result.is_ok());
+                assert_eq!(
+                    *calls.lock().unwrap(),
+                    [
+                        "prepare:web-image",
+                        "prepare:api-image",
+                        "stop",
+                        "remove",
+                        "start"
+                    ]
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn only_exact_digest_refs_may_skip_update_registry_pull() {
+        let digest = "ab".repeat(32);
+        assert!(immutable_update_image(&format!(
+            "localhost/lfg2025/indeedhub:1.0.1@sha256:{digest}"
+        )));
+        assert!(immutable_update_image(&format!(
+            "registry.example/app@sha256:{digest}"
+        )));
+        for mutable_or_invalid in [
+            "localhost/lfg2025/indeedhub:1.0.1".to_string(),
+            "registry.example/app:latest".to_string(),
+            format!("registry.example/app@sha256:{}", "g".repeat(64)),
+            "registry.example/app@sha256:abcd".to_string(),
+            format!("@sha256:{digest}"),
+            format!("registry.example/app@other@sha256:{digest}"),
+        ] {
+            assert!(!immutable_update_image(&mutable_or_invalid));
+        }
+    }
+
+    #[test]
+    fn mempool_update_preflight_rejects_stale_catalog_without_reinstalling() {
+        let installed = vec![(
+            "mempool".into(),
+            "r.test/lfg2025/mempool-frontend:v3.3.1-archy1".into(),
+        )];
+        let stale = vec![(
+            "archy-mempool-web".into(),
+            "r.test/lfg2025/mempool-frontend:v3.3.1".into(),
+        )];
+        assert!(update_targets_need_change(&stale, &installed).is_err());
+        let current = vec![(
+            "archy-mempool-web".into(),
+            "r.test/chaum/mempool-frontend:v3.3.1-archy1".into(),
+        )];
+        assert!(!update_targets_need_change(&current, &installed).unwrap());
+        let legacy = vec![(
+            "mempool-web".into(),
+            "r.test/old/mempool-frontend:v3.3.1-archy1".into(),
+        )];
+        assert!(!update_targets_need_change(&current, &legacy).unwrap());
+        let newer = vec![(
+            "archy-mempool-web".into(),
+            "r.test/chaum/mempool-frontend:v3.3.1-archy2".into(),
+        )];
+        assert!(update_targets_need_change(&newer, &installed).unwrap());
+    }
+
+    #[test]
+    fn stack_update_checks_backend_even_when_frontend_matches() {
+        let installed = vec![
+            ("mempool".into(), "r.test/team/web:3.3.1-archy1".into()),
+            ("mempool-api".into(), "r.test/team/api:3.3.1".into()),
+        ];
+        let mut targets = vec![
+            (
+                "archy-mempool-web".into(),
+                "r.test/team/web:3.3.1-archy1".into(),
+            ),
+            ("mempool-api".into(), "r.test/team/api:3.3.2".into()),
+        ];
+        assert!(update_targets_need_change(&targets, &installed).unwrap());
+        targets[0].1 = "r.test/team/web:3.3.1".into();
+        assert!(update_targets_need_change(&targets, &installed).is_err());
+    }
+
+    #[test]
+    fn update_completion_requires_the_target_version_to_be_installed() {
+        let targets = vec![(
+            "archy-mempool-web".into(),
+            "r.test/chaum/mempool-frontend:v3.3.1-archy1".into(),
+        )];
+        let mut installed = vec![(
+            "mempool".into(),
+            "r.test/lfg2025/mempool-frontend:v3.3.1".into(),
+        )];
+        assert!(verify_update_targets(&targets, &installed).is_err());
+        assert!(verify_update_targets(&targets, &[]).is_err());
+        installed[0].1 = "r.test/lfg2025/mempool-frontend:v3.3.1-archy1".into();
+        assert!(verify_update_targets(&targets, &installed).is_ok());
+    }
+
     #[test]
     fn legacy_flow_for_stack_apps() {
-        for app in ["immich", "penpot", "indeedhub"] {
+        for app in [
+            "immich",
+            "penpot",
+            "indeedhub",
+            "mempool",
+            "btcpay-server",
+            "netbird",
+        ] {
             assert!(uses_legacy_update_flow(app), "{app} should stay legacy");
         }
     }
 
     #[test]
     fn orchestrator_flow_for_single_apps() {
-        for app in [
-            "lnd",
-            "bitcoin-core",
-            "searxng",
-            "grafana",
-            "btcpay-server",
-            "mempool",
-            "fedimint",
-        ] {
+        for app in ["lnd", "bitcoin-core", "searxng", "grafana", "fedimint"] {
             assert!(
                 !uses_legacy_update_flow(app),
                 "{app} should be orchestrator-first"

core/archipelago/src/api/rpc/playback.rs

@@ -0,0 +1,248 @@
+//! Native broker only: settled purchases become session-bound opaque media URLs.
+use super::RpcHandler;
+use anyhow::{Context, Result};
+use serde::Deserialize;
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Issue {
+    purchase_id: String,
+}
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Status {
+    handle: String,
+}
+impl RpcHandler {
+    async fn playback_context(
+        &self,
+        session: &Option<String>,
+    ) -> Result<(
+        String,
+        crate::container::registration_pin::InstalledAppContext,
+    )> {
+        let session = session.as_ref().context("Owner session required")?;
+        anyhow::ensure!(
+            self.session_store.validate(session).await,
+            "Owner session expired"
+        );
+        let identity =
+            crate::identity::NodeIdentity::load_existing(&self.config.data_dir.join("identity"))
+                .await?;
+        let (state, _) = self.state_manager.get_snapshot().await;
+        let root = self.config.data_dir.clone();
+        let context = tokio::task::spawn_blocking(move || {
+            crate::container::registration_pin::installed_context(&root, &identity, &state)
+        })
+        .await??;
+        Ok((session.clone(), context))
+    }
+    pub(super) async fn handle_playback_handle(
+        &self,
+        params: Option<serde_json::Value>,
+        session: &Option<String>,
+    ) -> Result<serde_json::Value> {
+        let params: Issue = serde_json::from_value(params.context("Missing purchase identifier")?)?;
+        let (session, context) = self.playback_context(session).await?;
+        let handle = self
+            .playback_handles()
+            .issue(
+                &self.config.data_dir,
+                context.clone(),
+                &session,
+                &params.purchase_id,
+            )
+            .await?;
+        let expires = self
+            .playback_handles()
+            .expiry(&handle, &session, &context)?;
+        Ok(serde_json::json!({"handle":handle,"expires_at":expires}))
+    }
+    pub(super) async fn handle_playback_status(
+        &self,
+        params: Option<serde_json::Value>,
+        session: &Option<String>,
+    ) -> Result<serde_json::Value> {
+        let params: Status = serde_json::from_value(params.context("Missing playback handle")?)?;
+        let (session, context) = self.playback_context(session).await?;
+        let expires = self
+            .playback_handles()
+            .expiry(&params.handle, &session, &context)?;
+        Ok(serde_json::json!({"expires_at":expires}))
+    }
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Prepare {
+    handle: String,
+    #[serde(default)]
+    retry: bool,
+}
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Start {
+    handle: String,
+    ready_id: String,
+}
+impl RpcHandler {
+    async fn playback_control(
+        &self,
+        handle: &str,
+        ready_id: Option<&str>,
+        retry: bool,
+        session: &Option<String>,
+    ) -> Result<serde_json::Value> {
+        let (session, context) = self.playback_context(session).await?;
+        let binding = self.playback_handles().lookup(handle, &session, &context)?;
+        let (capability, duration) = {
+            let journal = crate::content_purchase::Journal::open(&self.config.data_dir).await?;
+            let record = journal
+                .buyer(&binding.contract.id)
+                .await?
+                .context("Original purchase missing")?;
+            anyhow::ensure!(
+                record.contract == binding.contract,
+                "Original purchase changed"
+            );
+            let capability = record
+                .receipt()
+                .context("Original payment is not settled")?
+                .capability
+                .clone();
+            let envelope = journal
+                .protocol_envelope("buyer", &binding.contract.id)
+                .await?
+                .context("Original rental terms missing")?;
+            (
+                capability,
+                envelope
+                    .offer
+                    .viewing_seconds
+                    .context("Purchase is not a timed rental")?,
+            )
+        };
+        let peer = crate::federation::load_unique_payment_peer(
+            &self.config.data_dir,
+            &binding.seller_onion,
+        )
+        .await?;
+        anyhow::ensure!(
+            peer.did == binding.contract.seller_did,
+            "Purchased seller identity changed"
+        );
+        let mesh = peer.fips_npub.context("Seller mesh binding unavailable")?;
+        let action = if ready_id.is_some() {
+            "start"
+        } else {
+            "prepare"
+        };
+        let path = format!(
+            "/content/{}/rental/{}/{action}",
+            binding.contract.content_id, binding.contract.id
+        );
+        let body = serde_json::json!({"capability":capability,"ready_id":ready_id,"retry":retry});
+        let (mut response, _) =
+            crate::fips::dial::PeerRequest::new(Some(&mesh), &binding.seller_onion, &path)
+                .require_fips()
+                .single_delivery()
+                .timeout(std::time::Duration::from_secs(20))
+                .send_content_json(&self.config.data_dir, &binding.contract.seller_did, &body)
+                .await?;
+        anyhow::ensure!(
+            response.status().is_success(),
+            "Original rental is unavailable; retry this purchase without paying again"
+        );
+        let mut bytes = Vec::new();
+        while let Some(chunk) = response.chunk().await? {
+            anyhow::ensure!(
+                bytes
+                    .len()
+                    .checked_add(chunk.len())
+                    .is_some_and(|n| n <= 16 * 1024),
+                "Rental control response too large"
+            );
+            bytes.extend_from_slice(&chunk);
+        }
+        let remote: serde_json::Value = serde_json::from_slice(&bytes)?;
+        let state = remote["state"].as_str().context("Missing rental state")?;
+        let window = match (remote["started_at"].as_u64(), remote["expires_at"].as_u64()) {
+            (None, None) if remote["started_at"].is_null() && remote["expires_at"].is_null() => {
+                None
+            }
+            (Some(started), Some(expires))
+                if started > 0 && started.checked_add(duration) == Some(expires) =>
+            {
+                Some((started, expires))
+            }
+            _ => anyhow::bail!("Seller changed the original rental window"),
+        };
+        let (started_at, expires_at) =
+            window.map_or((None, None), |(start, end)| (Some(start), Some(end)));
+        let result = match state {
+            "preparing" if ready_id.is_none() => {
+                let completed = remote["completed_bytes"]
+                    .as_u64()
+                    .context("Invalid verification progress")?;
+                anyhow::ensure!(
+                    remote["total_bytes"].as_u64() == Some(binding.contract.content_size)
+                        && completed <= binding.contract.content_size
+                        && remote["viewing_seconds"].as_u64() == Some(duration),
+                    "Rental preparation terms changed"
+                );
+                serde_json::json!({"state":"preparing","completed_bytes":completed,"total_bytes":binding.contract.content_size,
+                    "viewing_seconds":duration,"started_at":started_at,"expires_at":expires_at})
+            }
+            "ready" if ready_id.is_none() => {
+                let id = remote["ready_id"]
+                    .as_str()
+                    .context("Missing readiness identifier")?;
+                let parsed = uuid::Uuid::parse_str(id)?;
+                anyhow::ensure!(
+                    parsed.to_string() == id
+                        && parsed.get_version_num() == 4
+                        && remote["total_bytes"].as_u64() == Some(binding.contract.content_size)
+                        && remote["viewing_seconds"].as_u64() == Some(duration),
+                    "Rental readiness changed"
+                );
+                serde_json::json!({"state":"ready","ready_id":id,"handle":handle,"viewing_seconds":duration,
+                    "started_at":started_at,"expires_at":expires_at})
+            }
+            "unavailable" if ready_id.is_none() => {
+                serde_json::json!({"state":"unavailable","expires_at":expires_at})
+            }
+            "expired" if window.is_some() => {
+                serde_json::json!({"state":"expired","started_at":started_at,"expires_at":expires_at})
+            }
+            "started" if ready_id.is_some() && window.is_some() => {
+                serde_json::json!({"state":"started","started_at":started_at,
+                "expires_at":expires_at,"playback_url":format!("/api/rental-playback/{handle}")})
+            }
+            _ => {
+                anyhow::bail!("Unexpected rental state; recover this purchase without paying again")
+            }
+        };
+        if let Some((_, expires)) = window {
+            self.playback_handles()
+                .note_expiry(handle, &binding, expires)?;
+        }
+        Ok(result)
+    }
+    pub(super) async fn handle_playback_prepare(
+        &self,
+        params: Option<serde_json::Value>,
+        session: &Option<String>,
+    ) -> Result<serde_json::Value> {
+        let input: Prepare = serde_json::from_value(params.context("Missing playback handle")?)?;
+        self.playback_control(&input.handle, None, input.retry, session)
+            .await
+    }
+    pub(super) async fn handle_playback_start(
+        &self,
+        params: Option<serde_json::Value>,
+        session: &Option<String>,
+    ) -> Result<serde_json::Value> {
+        let input: Start = serde_json::from_value(params.context("Missing readiness identifier")?)?;
+        self.playback_control(&input.handle, Some(&input.ready_id), false, session)
+            .await
+    }
+}

core/archipelago/src/api/rpc/purchase.rs

@@ -0,0 +1,253 @@
+//! Owner RPC for permanent Cloud purchases. Registered app rentals use the
+//! separate native installed-app context + opaque playback-handle dispatcher.
+use super::RpcHandler;
+use crate::{
+    content_purchase::Journal,
+    content_purchase_caller::{self as caller, PurchaseConsent, PurchaseTransport, ReadyPurchase},
+    content_purchase_transport::FipsPurchaseTransport,
+};
+use anyhow::{Context, Result};
+use serde::Deserialize;
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct PurchaseParams {
+    onion: String,
+    content_id: String,
+    filename: Option<String>,
+    max_wallet_debit: u64,
+    consent: Option<PurchaseConsent>,
+}
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct CancelParams {
+    onion: String,
+    operation_id: String,
+}
+impl RpcHandler {
+    pub(super) async fn handle_content_purchase(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params: PurchaseParams =
+            serde_json::from_value(params.context("Missing purchase parameters")?)?;
+        anyhow::ensure!(
+            !params.content_id.starts_with("registered_"),
+            "Registered rentals require the native app purchase context"
+        );
+        let transport =
+            FipsPurchaseTransport::load(self.config.data_dir.clone(), params.onion.clone()).await?;
+        let identity =
+            crate::identity::NodeIdentity::load_existing(&self.config.data_dir.join("identity"))
+                .await?;
+        let buyer = identity.did_key()?;
+        let _rail = crate::content_payment_admission::lock(
+            &self.config.data_dir,
+            &buyer,
+            transport.seller_did(),
+            &params.content_id,
+        )
+        .await?;
+        self.ensure_onchain_allows_other_rail(&buyer, transport.seller_did(), &params.content_id)
+            .await?;
+        self.ensure_invoice_allows_other_rail(&buyer, transport.seller_did(), &params.content_id)
+            .await?;
+
+        let result = caller::purchase(
+            &self.config.data_dir,
+            &buyer,
+            &params.content_id,
+            params.filename.as_deref(),
+            params.max_wallet_debit,
+            params.consent.as_ref(),
+            &transport,
+        )
+        .await?;
+        match result {
+            ReadyPurchase::Preparing { .. } => {
+                anyhow::bail!("Ordinary purchase cannot prepare a timed rental")
+            }
+            ReadyPurchase::AwaitingConfirmation {
+                operation_id,
+                envelope_sha256,
+                gross_token_sats,
+                seller_net_sats,
+                wallet_debit_sats,
+                expires_at,
+                network,
+                mint_url,
+            } => Ok(
+                serde_json::json!({"state":"confirmation_required","operation_id":operation_id,
+                    "envelope_sha256":envelope_sha256,"gross_token_sats":gross_token_sats,
+                    "seller_net_sats":seller_net_sats,"wallet_debit_sats":wallet_debit_sats,"expires_at":expires_at,"network":network,"mint_url":mint_url}),
+            ),
+            ReadyPurchase::Cancelled { operation_id } => {
+                Ok(serde_json::json!({"state":"cancelled_unspent","operation_id":operation_id}))
+            }
+            ReadyPurchase::Cached { content_id, .. } => Ok(
+                serde_json::json!({"state":"delivered","owned":true,"owned_content_id":content_id}),
+            ),
+            ReadyPurchase::Entitlement { contract, receipt } => {
+                let item = crate::content_purchase_download::cache(
+                    &self.config.data_dir,
+                    &params.onion,
+                    &contract,
+                    &receipt,
+                )
+                .await?;
+                Ok(
+                    serde_json::json!({"state":"delivered","owned":true,"operation_id":contract.id,
+                    "owned_content_id":item.content_id,"mime_type":item.mime_type,"size_bytes":item.size_bytes}),
+                )
+            }
+        }
+    }
+    pub(super) async fn handle_content_cancel_purchase(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params: CancelParams =
+            serde_json::from_value(params.context("Missing cancellation parameters")?)?;
+        let transport =
+            FipsPurchaseTransport::load(self.config.data_dir.clone(), params.onion).await?;
+        let identity =
+            crate::identity::NodeIdentity::load_existing(&self.config.data_dir.join("identity"))
+                .await?;
+        let (envelope, plan) = {
+            let journal = Journal::open(&self.config.data_dir).await?;
+            let record = journal
+                .buyer(&params.operation_id)
+                .await?
+                .context("Original purchase not found")?;
+            anyhow::ensure!(
+                record.contract.buyer_did == identity.did_key()?
+                    && record.contract.seller_did == transport.seller_did(),
+                "Cancellation purchase binding changed"
+            );
+            (
+                journal
+                    .protocol_envelope("buyer", &params.operation_id)
+                    .await?
+                    .context("Original payment shape missing")?,
+                journal
+                    .buyer_plan(&params.operation_id)
+                    .await?
+                    .context("Original wallet plan missing")?,
+            )
+        };
+        caller::cancel_purchase(&self.config.data_dir, &envelope, &plan, &transport).await?;
+        Ok(serde_json::json!({"state":"cancelled_unspent","operation_id":params.operation_id}))
+    }
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RentalParams {
+    #[serde(default)]
+    retry_preparation: bool,
+    seller_did: String,
+    content_id: String,
+    expected_sha256: String,
+    expected_price_sats: u64,
+    expected_viewing_seconds: u64,
+    max_wallet_debit: u64,
+    consent: Option<PurchaseConsent>,
+}
+impl RpcHandler {
+    pub(super) async fn handle_content_rental_purchase(
+        &self,
+        input: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params: RentalParams =
+            serde_json::from_value(input.context("Missing rental purchase terms")?)?;
+        anyhow::ensure!(
+            params.content_id.starts_with("registered_")
+                && params.expected_price_sats > 0
+                && (1..=31_536_000).contains(&params.expected_viewing_seconds)
+                && params.expected_sha256.len() == 64
+                && params
+                    .expected_sha256
+                    .bytes()
+                    .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b)),
+            "Invalid published rental terms"
+        );
+        let identity =
+            crate::identity::NodeIdentity::load_existing(&self.config.data_dir.join("identity"))
+                .await?;
+        let buyer = identity.did_key()?;
+        let onion = crate::content_purchase_transport::seller_onion_for_did(
+            &self.config.data_dir,
+            &params.seller_did,
+        )
+        .await?;
+        let transport = FipsPurchaseTransport::load(self.config.data_dir.clone(), onion.clone())
+            .await?
+            .retry_preparation(params.retry_preparation);
+        // Hold the same outer admission lock as every other payment rail,
+        // including quote recovery and delayed consent callbacks. Check journals
+        // only after locking so an in-flight alternate rail cannot be missed.
+        let _rail = crate::content_payment_admission::lock(
+            &self.config.data_dir,
+            &buyer,
+            transport.seller_did(),
+            &params.content_id,
+        )
+        .await?;
+        self.ensure_onchain_allows_other_rail(&buyer, transport.seller_did(), &params.content_id)
+            .await?;
+        self.ensure_invoice_allows_other_rail(&buyer, transport.seller_did(), &params.content_id)
+            .await?;
+        let (state, _) = self.state_manager.get_snapshot().await;
+        let data = self.config.data_dir.clone();
+        tokio::task::spawn_blocking(move || {
+            crate::container::registration_pin::installed_context(&data, &identity, &state)
+        })
+        .await??;
+        let expected = caller::ExpectedRental {
+            seller_did: params.seller_did,
+            content_id: params.content_id.clone(),
+            sha256: params.expected_sha256,
+            price_sats: params.expected_price_sats,
+            viewing_seconds: params.expected_viewing_seconds,
+        };
+        match caller::purchase_bound(
+            &self.config.data_dir,
+            &buyer,
+            &params.content_id,
+            None,
+            params.max_wallet_debit,
+            params.consent.as_ref(),
+            &transport,
+            Some(&expected),
+        )
+        .await?
+        {
+            ReadyPurchase::Preparing {
+                completed_bytes,
+                total_bytes,
+            } => Ok(serde_json::json!({
+                "state":"preparing", "completed_bytes":completed_bytes,"total_bytes":total_bytes})),
+            ReadyPurchase::AwaitingConfirmation {
+                operation_id,
+                envelope_sha256,
+                gross_token_sats,
+                seller_net_sats,
+                wallet_debit_sats,
+                expires_at,
+                network,
+                mint_url,
+            } => Ok(serde_json::json!({
+                "state":"confirmation_required","operation_id":operation_id,"envelope_sha256":envelope_sha256,
+                "gross_token_sats":gross_token_sats,"seller_net_sats":seller_net_sats,"wallet_debit_sats":wallet_debit_sats,
+                "expires_at":expires_at,"seller_onion":onion,"network":network,"mint_url":mint_url})),
+            ReadyPurchase::Entitlement { contract, .. } => Ok(
+                serde_json::json!({"state":"entitled","operation_id":contract.id,"seller_onion":onion}),
+            ),
+            ReadyPurchase::Cancelled { operation_id } => Ok(
+                serde_json::json!({"state":"cancelled_unspent","operation_id":operation_id,"seller_onion":onion}),
+            ),
+            ReadyPurchase::Cached { .. } => {
+                anyhow::bail!("A timed rental cannot use a permanent owned copy")
+            }
+        }
+    }
+}

core/archipelago/src/api/rpc/system/handlers.rs

@@ -780,6 +780,19 @@ impl TlsMaterial {
             );
         }
 
+        // nginx and the app gate share the leaf. Validate the daemon's read
+        // permission on the staged key before replacing either live file.
+        if self.privileged {
+            let mut repair = self.cmd("/usr/bin/python3");
+            repair.args([
+                "-c",
+                include_str!("../../../../../../scripts/repair-app-gate-tls-permissions.py"),
+                "--key-name",
+                TLS_KEY_STAGING_NAME,
+            ]);
+            run_checked(repair, "repair staged app TLS key permissions").await?;
+        }
+
         // rename(2) within one directory: a reader sees either the whole old
         // file or the whole new one, never a partial write. Two files cannot
         // be swapped in a single atomic step, so there is a sub-millisecond
@@ -1025,10 +1038,46 @@ impl RpcHandler {
             .ok_or_else(|| anyhow::anyhow!("Missing key"))?;
 
         match key {
-            "claude_api_key_set" => {
-                let key_file = self.config.data_dir.join("secrets/claude-api-key");
-                let has_key = tokio::fs::metadata(&key_file).await.is_ok();
-                Ok(serde_json::json!({ "value": has_key }))
+            "claude_api_key_set" | "openai_api_key_set" => {
+                let provider = if key == "claude_api_key_set" {
+                    "claude"
+                } else {
+                    "openai"
+                };
+                Ok(
+                    serde_json::json!({ "value": crate::settings::model_provider::has_key(&self.config.data_dir, provider).await }),
+                )
+            }
+            "ai_provider" => {
+                let settings =
+                    crate::settings::model_provider::ModelProvider::load(&self.config.data_dir)
+                        .await?;
+                Ok(serde_json::json!({ "value": settings }))
+            }
+            "ai_provider_status" => {
+                let settings =
+                    crate::settings::model_provider::ModelProvider::load(&self.config.data_dir)
+                        .await?;
+                let local = tokio::time::timeout(std::time::Duration::from_secs(4), async {
+                    let (detected, _) = crate::api::rpc::mesh::assistant::detect_ollama().await;
+                    detected
+                        && crate::assistant::backends::ollama::model_supports_tools(
+                            crate::assistant::backends::ollama::OLLAMA_BASE_URL,
+                            crate::assistant::backends::ollama::OLLAMA_DEFAULT_MODEL,
+                        )
+                        .await
+                });
+                let (claude, openai, local) = tokio::join!(
+                    crate::settings::model_provider::has_key(&self.config.data_dir, "claude"),
+                    crate::settings::model_provider::has_key(&self.config.data_dir, "openai"),
+                    local,
+                );
+                let budget = crate::assistant::AssistantBudget::load(&self.config.data_dir).await;
+                Ok(serde_json::json!({ "value": {
+                    "schema": 1, "settings": settings, "claude_configured": claude,
+                    "openai_configured": openai, "local_ready": local.ok(),
+                    "routstr_remaining_sats": budget.remaining_sats(),
+                }}))
             }
             _ => Ok(serde_json::json!({ "value": null })),
         }
@@ -1210,38 +1259,21 @@ impl RpcHandler {
         let value = params.get("value").and_then(|v| v.as_str()).unwrap_or("");
 
         match key {
-            "claude_api_key" => {
-                let secrets_dir = self.config.data_dir.join("secrets");
-                tokio::fs::create_dir_all(&secrets_dir)
-                    .await
-                    .context("Failed to create secrets dir")?;
-                let key_file = secrets_dir.join("claude-api-key");
-
-                if value.is_empty() {
-                    // Remove key
-                    tokio::fs::remove_file(&key_file).await.ok();
-                    info!("Claude API key removed");
+            "claude_api_key" | "openai_api_key" => {
+                let provider = if key == "claude_api_key" {
+                    "claude"
                 } else {
-                    // Save key
-                    tokio::fs::write(&key_file, value)
-                        .await
-                        .context("Failed to write API key")?;
-                    #[cfg(unix)]
-                    {
-                        use std::os::unix::fs::PermissionsExt;
-                        std::fs::set_permissions(&key_file, std::fs::Permissions::from_mode(0o600))
-                            .ok();
+                    "openai"
+                };
+                crate::settings::model_provider::save_key(&self.config.data_dir, provider, value)
+                    .await?;
+                info!(provider, "AI provider credential updated");
+                Ok(serde_json::json!({ "saved": true }))
             }
-                    info!("Claude API key saved");
-                }
-
-                // `secrets/claude-api-key` (above) is deliberately the ONLY
-                // Claude key ledger on this node (13-02-PLAN.md). A second
-                // copy used to be written alongside it for a standalone,
-                // unauthenticated sidecar process on port 3142 — that
-                // sidecar and its key copy are retired; the session-gated
-                // Rust daemon reads this one file directly.
-
+            "ai_provider" => {
+                let settings: crate::settings::model_provider::ModelProvider =
+                    serde_json::from_str(value).context("Invalid AI provider settings")?;
+                settings.save(&self.config.data_dir).await?;
                 Ok(serde_json::json!({ "saved": true }))
             }
             _ => anyhow::bail!("Unknown setting: {}", key),