@craft-native/android 0.0.451 → 0.0.464

package/templates/CraftNativeNotificationReceiver.kt.template

@@ -15,30 +15,228 @@ import org.json.JSONObject
 /** Delivers native-runtime notifications even when the app process has exited. */
 internal class CraftNativeNotificationReceiver : BroadcastReceiver() {
     override fun onReceive(context: Context, intent: Intent) {
+        intent.getStringExtra("craft.dismissedId")?.let {
+            CraftNativeNotifications.cancel(context, it, intent.getStringExtra("craft.dismissedThread"))
+            return
+        }
+        if (intent.hasExtra("craft.actionToken")) {
+            val pending = goAsync()
+            CraftNativeNotifications.receiveAction(context, intent) { pending.finish() }
+            return
+        }
         val id = intent.getStringExtra("id").orEmpty()
         if (id.isEmpty()) return
         val storage = context.getSharedPreferences("craft-native-notifications", Context.MODE_PRIVATE)
         val value = storage.getString(id, null)?.let { runCatching { JSONObject(it) }.getOrNull() } ?: return
         storage.edit().remove(id).commit()
+        CraftNativeNotifications.show(context, value, id, "craft_notifications")
+    }
+}
+
+/** Shared by scheduled locals and app-rendered FCM data messages. */
+internal object CraftNativeNotifications {
+    private const val REPLY = "craft.reply"
+
+    private fun config(context: Context): JSONObject = runCatching {
+        context.assets.open("craft.config.json").bufferedReader().use { JSONObject(it.readText()) }
+    }.getOrDefault(JSONObject())
+
+    internal fun actions(config: JSONObject, categoryId: String): List<JSONObject> {
+        val categories = config.optJSONArray("notificationCategories") ?: return emptyList()
+        for (index in 0 until categories.length()) {
+            val category = categories.optJSONObject(index) ?: continue
+            if (category.optString("id") != categoryId) continue
+            val entries = category.optJSONArray("actions") ?: return emptyList()
+            return (0 until entries.length()).mapNotNull { entries.optJSONObject(it) }
+        }
+        return emptyList()
+    }
+
+    internal fun actionDetail(config: JSONObject, value: JSONObject, actionId: String, reply: CharSequence?): JSONObject? {
+        val categoryId = value.optString("categoryId")
+        val action = actions(config, categoryId).firstOrNull { it.optString("id") == actionId } ?: return null
+        val detail = JSONObject().put("actionId", actionId).put("notificationId", value.optString("id"))
+            .put("categoryId", categoryId).put("data", value.optJSONObject("data") ?: JSONObject())
+        if (reply != null && action.optJSONObject("textInput") != null) detail.put("userText", reply.toString())
+        return detail
+    }
+
+    internal fun invalidOptions(value: JSONObject): String? {
+        for (key in listOf("categoryId", "threadIdentifier")) {
+            if (value.has(key) && value.opt(key) !is String) return "$key must be a string"
+        }
+        if (value.has("interruptionLevel") && value.opt("interruptionLevel") !in listOf("passive", "active", "timeSensitive")) {
+            return "interruptionLevel must be passive, active or timeSensitive"
+        }
+        return null
+    }
+
+    internal fun consumeAction(storage: android.content.SharedPreferences, token: String): JSONObject? {
+        val saved = storage.getString(token, null)?.let { runCatching { JSONObject(it) }.getOrNull() } ?: return null
+        if (!storage.edit().remove(token).commit()) return null
+        return saved
+    }
+
+    @Synchronized
+    fun receiveAction(context: Context, intent: Intent?, queued: (() -> Unit)? = null): Boolean {
+        val token = intent?.getStringExtra("craft.actionToken") ?: return false.also { queued?.invoke() }
+        val storage = context.getSharedPreferences("craft-native-notification-actions", Context.MODE_PRIVATE)
+        // MainActivity is exported. Never turn arbitrary launch extras into
+        // an authenticated notification action: only a token we minted can
+        // name an action/payload. RemoteInput supplies just the reply text.
+        val saved = consumeAction(storage, token)
+        if (saved == null) { queued?.invoke(); return true }
+        intent.removeExtra("craft.actionToken")
+        val value = saved.optJSONObject("value") ?: return true.also { queued?.invoke() }
+        val actionId = saved.optString("actionId")
+        val detail = actionDetail(config(context), value, actionId,
+            androidx.core.app.RemoteInput.getResultsFromIntent(intent)?.getCharSequence(REPLY))
+        if (detail == null) { queued?.invoke(); return true }
+        cancel(context, detail.optString("notificationId"))
+        CraftNativeBackground.runOnce(context, "craftNotificationAction", detail, queued)
+        return true
+    }
+
+    @Synchronized
+    fun revoke(context: Context, notificationId: String? = null) {
+        val storage = context.getSharedPreferences("craft-native-notification-actions", Context.MODE_PRIVATE)
+        if (notificationId == null) { storage.edit().clear().commit(); return }
+        val tokens = storage.all.filter { (key, raw) ->
+            !key.startsWith("index:") && runCatching { JSONObject(raw as String).optJSONObject("value")?.optString("id") == notificationId }.getOrDefault(false)
+        }.keys
+        val edit = storage.edit()
+        storage.all.forEach { (key, value) -> if (key in tokens || (key.startsWith("index:") && value is String && value in tokens)) edit.remove(key) }
+        edit.commit()
+    }
+
+    @Synchronized
+    fun clearEmptyGroup(context: Context, thread: String?) {
+        if (thread.isNullOrEmpty()) return
+        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+        val children = notificationGroups(context).all.any { (key, value) ->
+            key.startsWith("notification:") && value == thread
+        }
+        if (!children) manager.cancel("craft.group:$thread", 1)
+    }
+
+    @Synchronized
+    fun cancel(context: Context, id: String, dismissedThread: String? = null) {
+        revoke(context, id)
+        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+        val groups = notificationGroups(context)
+        val thread = groups.getString("notification:$id", null) ?: dismissedThread
+        check(groups.edit().remove("notification:$id").commit()) { "Could not save notification cancellation" }
+        manager.cancel(id, 0)
+        clearEmptyGroup(context, thread)
+    }
+
+    @Synchronized
+    fun cancelAll(context: Context) {
+        revoke(context)
+        check(notificationGroups(context).edit().clear().putBoolean("initialized", true).commit()) { "Could not clear notification groups" }
+        (context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager).cancelAll()
+    }
+
+    private fun notificationGroups(context: Context): android.content.SharedPreferences {
+        val storage = context.getSharedPreferences("craft-native-notification-groups", Context.MODE_PRIVATE)
+        if (!storage.getBoolean("initialized", false)) {
+            // Adopt notifications posted by earlier app versions once. After
+            // migration, our durable intent owns membership: OS snapshots can
+            // lag both notify() and cancel(), including across receiver calls.
+            val manager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+            val edit = storage.edit().putBoolean("initialized", true)
+            manager.activeNotifications.filter {
+                it.tag != null && it.id == 0 && (it.notification.flags and android.app.Notification.FLAG_GROUP_SUMMARY) == 0
+            }.forEach { entry ->
+                entry.notification.group?.takeIf { it.isNotEmpty() }?.let { edit.putString("notification:${entry.tag}", it) }
+            }
+            check(edit.commit()) { "Could not initialize notification groups" }
+        }
+        return storage
+    }
+
+    private fun pending(context: Context, value: JSONObject, action: JSONObject?): android.app.PendingIntent? {
+        val foreground = action == null || action.optBoolean("foreground", false)
+        val target = if (foreground) Intent(context, MainActivity::class.java)
+            .addFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP)
+        else Intent(context, CraftNativeNotificationReceiver::class.java)
+        target.action = "craft.notification:" + android.net.Uri.encode(value.optString("id")) + ":" +
+            (if (action == null) "tap" else "action:" + android.net.Uri.encode(action.optString("id")))
+        target.putExtra("craft.notification", true)
+        if (action == null) target.putExtra("craft.notification.data", (value.optJSONObject("data") ?: JSONObject()).toString())
+        else {
+            val token = java.util.UUID.randomUUID().toString()
+            val storage = context.getSharedPreferences("craft-native-notification-actions", Context.MODE_PRIVATE)
+            val index = "index:" + target.action
+            val edit = storage.edit()
+            storage.getString(index, null)?.let { edit.remove(it) }
+            if (!edit.putString(index, token).putString(token, JSONObject().put("actionId", action.optString("id"))
+                .put("value", value).toString()).commit()) return null
+            target.putExtra("craft.actionToken", token)
+        }
+        val mutable = action?.optJSONObject("textInput") != null
+        val flags = android.app.PendingIntent.FLAG_UPDATE_CURRENT or
+            (if (mutable) android.app.PendingIntent.FLAG_MUTABLE else android.app.PendingIntent.FLAG_IMMUTABLE)
+        return if (foreground) android.app.PendingIntent.getActivity(context, 0, target, flags)
+        else android.app.PendingIntent.getBroadcast(context, 0, target, flags)
+    }
+
+    @Synchronized
+    fun show(context: Context, original: JSONObject, id: String, channel: String) {
+        if (invalidOptions(original) != null) return
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU &&
             ContextCompat.checkSelfPermission(context, Manifest.permission.POST_NOTIFICATIONS) != PackageManager.PERMISSION_GRANTED) return
-
+        revoke(context, id) // replacing a notification also invalidates removed actions
+        val value = JSONObject(original.toString()).put("id", id)
         val manager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
-        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-            manager.createNotificationChannel(NotificationChannel(
-                "craft_notifications",
-                "Craft Notifications",
-                NotificationManager.IMPORTANCE_DEFAULT,
-            ))
-        }
-        val notification = NotificationCompat.Builder(context, "craft_notifications")
+        val level = value.optString("interruptionLevel", "active")
+        val channelId = if (level == "active") channel else "$channel.$level"
+        val importance = when (level) {
+            "passive" -> NotificationManager.IMPORTANCE_LOW
+            "timeSensitive" -> NotificationManager.IMPORTANCE_HIGH
+            else -> NotificationManager.IMPORTANCE_DEFAULT
+        }
+        manager.createNotificationChannel(NotificationChannel(channelId, "${context.applicationInfo.loadLabel(context.packageManager)} ($level)", importance))
+        val notification = NotificationCompat.Builder(context, channelId)
             .setSmallIcon(R.drawable.craft_notification_icon)
             .setColor(ContextCompat.getColor(context, R.color.craft_notification_color))
-            .setContentTitle(value.optString("title"))
-            .setContentText(value.optString("body"))
-            .setPriority(NotificationCompat.PRIORITY_DEFAULT)
-            .setAutoCancel(true)
-            .build()
-        manager.notify(id, 0, notification)
+            .setContentTitle(value.optString("title")).setContentText(value.optString("body"))
+            .setStyle(NotificationCompat.BigTextStyle().bigText(value.optString("body")))
+            .setContentIntent(pending(context, value, null)).setAutoCancel(true)
+        val thread = value.optString("threadIdentifier")
+        if (thread.isNotEmpty()) notification.setGroup(thread)
+        actions(config(context), value.optString("categoryId")).filter {
+            // API <31 cannot enforce action authentication. Omit the action
+            // instead of silently weakening the app's request.
+            !it.optBoolean("authenticationRequired", false) || Build.VERSION.SDK_INT >= 31
+        }.forEach { item ->
+            val target = pending(context, value, item) ?: return@forEach
+            val action = NotificationCompat.Action.Builder(0, item.optString("title"), target)
+                .setAuthenticationRequired(item.optBoolean("authenticationRequired", false))
+            if (item.optBoolean("destructive", false)) action.setSemanticAction(NotificationCompat.Action.SEMANTIC_ACTION_DELETE)
+            item.optJSONObject("textInput")?.let { input ->
+                action.addRemoteInput(androidx.core.app.RemoteInput.Builder(REPLY)
+                    .setLabel(input.optString("placeholder", item.optString("title"))).build())
+                action.setAllowGeneratedReplies(true)
+            }
+            notification.addAction(action.build())
+        }
+        val dismissed = Intent(context, CraftNativeNotificationReceiver::class.java)
+            .setAction("craft.notification.dismiss:" + android.net.Uri.encode(id)).putExtra("craft.dismissedId", id).putExtra("craft.dismissedThread", thread)
+        notification.setDeleteIntent(android.app.PendingIntent.getBroadcast(context, 0, dismissed,
+            android.app.PendingIntent.FLAG_UPDATE_CURRENT or android.app.PendingIntent.FLAG_IMMUTABLE))
+        val groups = notificationGroups(context)
+        val previousThread = groups.getString("notification:$id", null)
+        val edit = groups.edit()
+        if (thread.isEmpty()) edit.remove("notification:$id") else edit.putString("notification:$id", thread)
+        check(edit.commit()) { "Could not save notification group" }
+        manager.notify(id, 0, notification.build())
+        if (thread.isNotEmpty()) {
+            manager.notify("craft.group:$thread", 1, NotificationCompat.Builder(context, channelId)
+                .setSmallIcon(R.drawable.craft_notification_icon)
+                .setContentTitle(context.applicationInfo.loadLabel(context.packageManager))
+                .setContentIntent(pending(context, value, null)).setGroup(thread).setGroupSummary(true).setAutoCancel(true).build())
+        }
+        if (previousThread != thread) clearEmptyGroup(context, previousThread)
     }
 }

package/templates/CraftNativeServices.kt.template

@@ -119,6 +119,7 @@ internal class CraftNativeServices(
         if (config.optBoolean("enableAudioRecording")) add("audioRecording")
         // Videos kept on the phone for offline (CraftNativeMedia).
         add("media")
+        add("media-cache-key")
         if (config.optBoolean("enableShare")) add("share")
         if (config.optBoolean("enablePushNotifications")) add("push")
         if (health != null || healthServices != null) {
@@ -139,7 +140,8 @@ internal class CraftNativeServices(
             if (CraftNative.supportsRecordingIntentIdentity()) add("locationRecordingIntentIdentity")
             if (CraftNative.supportsRecordingPowerMode()) add("locationRecordingPowerMode")
         }
-        if (config.optJSONObject("backgroundRefresh")?.optBoolean("enabled") == true || config.optBoolean("enablePushNotifications")) add("background")
+        if (config.optJSONObject("backgroundRefresh")?.optBoolean("enabled") == true || config.optBoolean("enablePushNotifications") ||
+            (config.optJSONArray("notificationCategories")?.length() ?: 0) > 0) add("background")
         // A Bluetooth heart-rate strap (CraftHeartRate.kt), the app's own
         // service: one connection and one recording for every screen.
         if (heartRateEnabled) addAll(listOf("heartRate", "heartRateRecordingOwnership", "heartRateRecordingIntentIdentity"))
@@ -179,11 +181,11 @@ internal class CraftNativeServices(
                 "Location" -> location(method, args, done)
                 "HeartRate" -> heartRate(method, args, done)
                 "Media" -> when (method) {
-                    "keep" -> CraftNativeMedia.keep(context, args.optString(0), args.optJSONObject(1)?.optJSONObject("headers") ?: JSONObject(), args.optJSONObject(1)?.optBoolean("cellular", true) ?: true, done)
-                    "path" -> done(success(CraftNativeMedia.local(context, args.optString(0))?.absolutePath ?: JSONObject.NULL))
+                    "keep" -> CraftNativeMedia.keep(context, args.optString(0), args.optJSONObject(1)?.optJSONObject("headers") ?: JSONObject(), args.optJSONObject(1)?.optBoolean("cellular", true) ?: true, cacheKey = args.optJSONObject(1)?.optString("cacheKey"), done = done)
+                    "path" -> done(success(CraftNativeMedia.local(context, CraftNativeMedia.identity(args.optString(0), args.optJSONObject(1)))?.absolutePath ?: JSONObject.NULL))
                     "prune" -> {
                         val keep = args.optJSONArray(0) ?: JSONArray()
-                        done(success(CraftNativeMedia.prune(context, (0 until keep.length()).map { keep.optString(it) })))
+                        done(success(CraftNativeMedia.prune(context, (0 until keep.length()).map { index -> keep.optJSONObject(index)?.let { CraftNativeMedia.identity(it.optString("url"), it) } ?: keep.optString(index) })))
                     }
                     "usage" -> done(success(CraftNativeMedia.usage(context)))
                     "clear" -> done(success(CraftNativeMedia.clear(context)))

package/templates/CraftNativeShell.kt.template

@@ -98,18 +98,21 @@ internal data class CraftNativeChromeFonts(val body: Typeface? = null, val headi
 
 /** The app's paths (`nativeScreens`), its tabs and its site. */
 internal class CraftNativeRoutes(config: JSONObject) {
-    private data class Route(val segments: List<String>, val screen: String)
+    private data class Route(val segments: List<String>, val screen: String, val constraints: Any?)
 
     /**
      * The iOS shell's order (CraftHybrid.swift's route table): a trailing
      * `*` last, then more fixed segments first, then longer patterns, then
      * by name, so `/m/store/library` is never taken for `/m/store/:slug`.
      */
+    private val validConstraints = !config.has("nativeScreenConstraints") || config.opt("nativeScreenConstraints") is JSONObject
+
     private val routes: List<Route> = buildList {
         val screens = config.optJSONObject("nativeScreens") ?: JSONObject()
+        val constraints = config.optJSONObject("nativeScreenConstraints")
         screens.keys().forEach { pattern ->
             val screen = screens.optString(pattern)
-            if (screen.isNotBlank()) add(Route(segmentsOf(pattern), screen))
+            if (screen.isNotBlank()) add(Route(segmentsOf(pattern), screen, constraints?.opt(pattern)))
         }
     }.sortedWith(
         compareBy<Route> { if (it.segments.lastOrNull() == "*") 1 else 0 }
@@ -189,11 +192,13 @@ internal class CraftNativeRoutes(config: JSONObject) {
 
     /** The screen that draws `path`, with its parameters and query as params. */
     fun match(path: String): CraftNativeRouteMatch? {
+        if (!validConstraints) return null
         val bare = normalize(path.substringBefore('#').substringBefore('?'))
         val query = path.substringBefore('#').substringAfter('?', "")
         val parts = segmentsOf(bare)
         for (route in routes) {
             val params = bind(route.segments, parts) ?: continue
+            if (!parametersAllowed(params, route.constraints)) continue
             if (query.isNotBlank()) {
                 query.split('&').filter { it.isNotBlank() }.forEach { pair ->
                     val key = Uri.decode(pair.substringBefore('='))
@@ -205,6 +210,33 @@ internal class CraftNativeRoutes(config: JSONObject) {
         return null
     }
 
+    private fun parametersAllowed(params: JSONObject, raw: Any?): Boolean {
+        if (raw == null) return true
+        val rules = raw as? JSONObject ?: return false
+        for (name in rules.keys()) {
+            var value = params.opt(name) as? String ?: return false
+            val rule = rules.optJSONObject(name) ?: return false
+            if (rule.keys().asSequence().any { it !in setOf("pattern", "exclude", "normalize") }) return false
+            if (rule.has("normalize") && rule.opt("normalize") != "lowercase") return false
+            val normalize = rule.has("normalize")
+            if (normalize) value = value.lowercase(java.util.Locale.ROOT)
+            if (rule.has("exclude")) {
+                val excluded = rule.optJSONArray("exclude") ?: return false
+                for (index in 0 until excluded.length()) {
+                    val item = excluded.opt(index) as? String ?: return false
+                    if (value == if (normalize) item.lowercase(java.util.Locale.ROOT) else item) return false
+                }
+            }
+            if (rule.has("pattern")) {
+                val pattern = rule.opt("pattern") as? String ?: return false
+                val expression = try { Regex(pattern) } catch (_: Exception) { return false }
+                if (!expression.matches(value)) return false
+            }
+            params.put(name, value)
+        }
+        return true
+    }
+
     private fun bind(pattern: List<String>, parts: List<String>): JSONObject? {
         val params = JSONObject()
         for (index in pattern.indices) {
@@ -739,44 +771,48 @@ internal object CraftNativePrelude {
           // Native capability ownership wins over any browser-shaped dialog
           // object the bundle installed before the bridge ran. Otherwise an
           // action sheet silently falls back to the DOM renderer.
-          var nextDialogRequest = 0;
-          function dialogRequest(method, args) {
+          var nextCapabilityRequest = 0;
+          function nativeRequest(module, method, args, untimed) {
               return new Promise(function(resolve, reject) {
-                var id = 'craft-dialog-' + (++nextDialogRequest);
+                var id = 'craft-host-' + (++nextCapabilityRequest);
                 var remove = __stxNativeBridge.addMessageListener(function(raw) {
                   var message;
                   try { message = typeof raw === 'string' ? JSON.parse(raw) : raw; } catch (error) { return; }
                   var payload = message && message.payload;
                   if (!payload || payload.requestId !== id) return;
+                  if (message.type !== 'API_ERROR' && message.type !== 'API_RESPONSE') return;
                   remove();
                   if (message.type === 'API_ERROR') {
-                    var failure = new Error(payload.message || 'Native dialog failed');
+                    var failure = new Error(payload.message || 'Native capability failed');
                     failure.code = payload.code || 'NATIVE_CALL_FAILED';
                     reject(failure);
                   } else if (message.type === 'API_RESPONSE') {
                     resolve(payload.data === undefined ? null : payload.data);
                   }
                 });
-                __stxNativeBridge.postMessage(JSON.stringify({
+                try { __stxNativeBridge.postMessage(JSON.stringify({
                   type: 'API_REQUEST',
                   id: id,
                   payload: {
                     version: __stxNativeBridge.capabilityProtocolVersion || 1,
-                    module: 'Dialog',
+                    module: module,
                     method: method,
                     args: args,
-                    untimed: true,
+                    untimed: untimed === true,
                   },
-                }));
+                })); } catch (error) { remove(); reject(error); }
               });
           }
           function installNativeDialog() {
             var craft = globalThis.craft = globalThis.craft || {};
+            craft.accessibility = {
+              announce: function(text, options) { return nativeRequest('Accessibility', 'announce', [text, options == null ? {} : options], false).then(function() {}); },
+            };
             if (Array.isArray(__stxNativeBridge.capabilities) && __stxNativeBridge.capabilities.indexOf('dialog') >= 0) {
               craft.dialog = {
-                alert: function(options) { return dialogRequest('alert', [options || {}]).then(function() {}); },
-                confirm: function(options) { return dialogRequest('confirm', [options || {}]).then(Boolean); },
-                actionSheet: function(options) { return dialogRequest('actionSheet', [options || {}]).then(function(id) { return typeof id === 'string' ? id : null; }); },
+                alert: function(options) { return nativeRequest('Dialog', 'alert', [options || {}], true).then(function() {}); },
+                confirm: function(options) { return nativeRequest('Dialog', 'confirm', [options || {}], true).then(Boolean); },
+                actionSheet: function(options) { return nativeRequest('Dialog', 'actionSheet', [options || {}], true).then(function(id) { return typeof id === 'string' ? id : null; }); },
               };
             }
           }
@@ -1334,6 +1370,12 @@ internal object CraftNativeSymbols {
  * transfer finishes on its own; the next keep answers from the copy.
  */
 internal object CraftNativeMedia {
+    /** Caller-owned account/resource/version identity; the request retains its authorized URL. */
+    fun identity(source: String, options: JSONObject?): String {
+        val key = options?.opt("cacheKey") as? String
+        return if (key != null && key.isNotEmpty() && key.toByteArray().size <= 1024) "craft-media-key:$key" else source
+    }
+
     const val ATTEMPT_SETTLED = "craft.media.attemptSettled"
     private const val TAG = "craft-media"
     private const val PREFS = "craft.media"
@@ -1373,14 +1415,22 @@ internal object CraftNativeMedia {
     /** The unique job for an address and connection rule: `any` or `wifi`. */
     private fun workName(address: String, wifiOnly: Boolean) = "$TAG:${digest(address)}:${if (wifiOnly) "wifi" else "any"}"
 
-    fun keep(context: Context, address: String, headers: JSONObject, cellular: Boolean, done: (CraftNativeCapabilityResult) -> Unit) {
-        val uri = runCatching { Uri.parse(address) }.getOrNull()
+    fun keep(context: Context, source: String, headers: JSONObject, cellular: Boolean, cacheKey: String? = null, done: (CraftNativeCapabilityResult) -> Unit) {
+        val address = identity(source, JSONObject().put("cacheKey", cacheKey))
+        val uri = runCatching { Uri.parse(source) }.getOrNull()
         if (uri == null || uri.scheme?.lowercase() !in setOf("http", "https") || uri.host.isNullOrBlank()) {
             return done(CraftNativeCapabilityResult(code = "INVALID_ARGUMENT", message = "media.keep needs an absolute http or https URL"))
         }
         val app = context.applicationContext
+        var sourceChanged = false
         val started = synchronized(lock) {
             local(app, address)?.let { return done(CraftNativeCapabilityResult(data = describe(address, it))) }
+            if (cacheKey != null) {
+                val sourceKey = "source:${digest(address)}"
+                val authorization = digest(source + "\n" + headers.keys().asSequence().sorted().joinToString("\n") { "$it:${headers.optString(it)}" })
+                sourceChanged = prefs(app).getString(sourceKey, null) != authorization
+                if (!prefs(app).edit().putString(sourceKey, authorization).commit()) return done(CraftNativeCapabilityResult(code = "IO_ERROR", message = "Could not persist media authorization"))
+            }
             generation(app).also { waiting.getOrPut(address) { mutableListOf() }.add(Waiting(it, done)) }
         }
         val wifiOnly = !cellular
@@ -1389,7 +1439,7 @@ internal object CraftNativeMedia {
         work.cancelUniqueWork(workName(address, !wifiOnly))
         val request = androidx.work.OneTimeWorkRequestBuilder<CraftNativeMediaWorker>()
             .setConstraints(androidx.work.Constraints.Builder().setRequiredNetworkType(if (wifiOnly) androidx.work.NetworkType.UNMETERED else androidx.work.NetworkType.CONNECTED).build())
-            .setInputData(androidx.work.workDataOf("address" to address, "headers" to headers.toString(), "generation" to started))
+            .setInputData(androidx.work.workDataOf("address" to address, "source" to source, "headers" to headers.toString(), "generation" to started))
             .setBackoffCriteria(androidx.work.BackoffPolicy.EXPONENTIAL, 30, java.util.concurrent.TimeUnit.SECONDS)
             .addTag(TAG)
             .addTag("$TAG:generation:$started")
@@ -1402,7 +1452,8 @@ internal object CraftNativeMedia {
             try {
                 if (generation(app) == started) {
                     val pending = work.getWorkInfosForUniqueWork(name).get().any {
-                        "$TAG:generation:$started" in it.tags && !it.progress.getBoolean(ATTEMPT_SETTLED, false) &&
+                        "$TAG:generation:$started" in it.tags &&
+                            !sourceChanged && !it.progress.getBoolean(ATTEMPT_SETTLED, false) &&
                             (it.state == androidx.work.WorkInfo.State.RUNNING ||
                                 (it.state == androidx.work.WorkInfo.State.ENQUEUED && it.runAttemptCount == 0))
                     }
@@ -1450,7 +1501,7 @@ internal object CraftNativeMedia {
      * file where it stopped, moves it into place whole, and answers whoever
      * waits. RETRY leaves the part file for the next attempt.
      */
-    fun transfer(context: Context, address: String, headers: JSONObject, started: Int, attempt: Int, beforeAnswer: () -> Unit = {}, stopped: () -> Boolean): Outcome {
+    fun transfer(context: Context, address: String, headers: JSONObject, started: Int, attempt: Int, source: String = address, beforeAnswer: () -> Unit = {}, stopped: () -> Boolean): Outcome {
         fun answer(result: CraftNativeCapabilityResult) {
             // The callback can immediately call keep again. Publish completion
             // before that callback, while WorkManager may still say RUNNING.
@@ -1485,8 +1536,8 @@ internal object CraftNativeMedia {
             val asked = headers.keys().asSequence().associateWith { headers.optString(it) }
             val fetched = try {
                 // A part that no longer lines up was dropped: the whole file, now, not after a backoff.
-                download.fetch(address, asked, staging, stopped).let { first ->
-                    if (first is CraftResumableDownload.Fetched.Restart) download.fetch(address, asked, staging, stopped) else first
+                download.fetch(source, asked, staging, stopped).let { first ->
+                    if (first is CraftResumableDownload.Fetched.Restart) download.fetch(source, asked, staging, stopped) else first
                 }
             } catch (error: Exception) {
                 val full = generateSequence<Throwable>(error) { it.cause }.take(16).any {
@@ -1684,7 +1735,7 @@ internal class CraftNativeMediaWorker(context: Context, parameters: androidx.wor
         val started = inputData.getInt("generation", 0)
         return try {
             setProgressAsync(androidx.work.workDataOf(CraftNativeMedia.ATTEMPT_SETTLED to false)).get()
-            val outcome = CraftNativeMedia.transfer(applicationContext, address, headers, started, runAttemptCount,
+            val outcome = CraftNativeMedia.transfer(applicationContext, address, headers, started, runAttemptCount, source = inputData.getString("source") ?: address,
                 beforeAnswer = { setProgressAsync(androidx.work.workDataOf(CraftNativeMedia.ATTEMPT_SETTLED to true)).get() }
             ) { isStopped }
             if (outcome == CraftNativeMedia.Outcome.RETRY) Result.retry() else Result.success()