akanjs 3.0.2 → 3.1.0-rc.0

package/vendor/@akanjs/native/plugins/updates/android/UpdatesPlugin.kt

@@ -3,10 +3,14 @@ package com.akanjs.plugins.updates
 import android.os.Handler
 import android.os.Looper
 import com.akanjs.runtime.AkanNativeErrorCode
+import com.akanjs.runtime.AkanNativeKernel
 import com.akanjs.runtime.AkanNativePluginContext
 import com.akanjs.runtime.AkanNativeReply
 import com.akanjs.runtime.AkanNativeUpdateConfig
+import com.akanjs.runtime.AkanNativeUpdateDecision
 import com.akanjs.runtime.AkanNativeUpdateEntry
+import com.akanjs.runtime.AkanNativeUpdateEnvelope
+import com.akanjs.runtime.AkanNativeUpdateReports
 import com.akanjs.runtime.AkanNativeUpdates
 import com.akanjs.runtime.AkanNativeVoidReply
 import java.io.File
@@ -14,13 +18,13 @@ import java.io.IOException
 import java.net.HttpURLConnection
 import java.net.URL
 import java.security.MessageDigest
-import java.util.Base64
 import org.json.JSONObject
 
 /**
- * Web bundle updates (UP-2), the Android twin of ios/UpdatesPlugin.swift: the manifest
- * `<url>/android/<channel>.json` is signed as a whole (`.sig`: base64 Ed25519 over its bytes, the
- * platform's on API 33+, AkanNativeEd25519 in plain Kotlin below), files are content-addressed (`<url>/android/files/<sha256>`)
+ * Web bundle updates (UP-2, protocol v2), the Android twin of ios/UpdatesPlugin.swift: the envelope
+ * `<url>/android/<channel>/<nativeApi>.json` carries the manifest's bytes, the keyId of the key of `updates.publicKeys`
+ * that signed them and the Ed25519 signature (the platform's on API 33+, AkanNativeEd25519 in plain Kotlin below);
+ * revocations and the sequence rule are AkanNativeKernel.updateDecision. Files are content-addressed (`<url>/android/files/<sha256>`)
  * and checked against their hash, and files the running bundle already has are copied. Which bundle
  * runs, and the trial / rollback rules, live in the shell (native/android/.../AkanNativeUpdates.kt).
  * Network and file work run on a worker thread; AkanNativeUpdates is only touched on the main thread.
@@ -31,19 +35,30 @@ class UpdatesPlugin(private val context: AkanNativePluginContext) : UpdatesPlugi
     /** The running download's call (one at a time); its cancellation stops the read loop. */
     @Volatile private var download: com.akanjs.runtime.AkanNativeCall? = null
 
-    private class Failure(val code: String, message: String) : Exception(message)
+    /** [report]: the reason a failed download is reported under (AkanNativeUpdateReports), null when it is not reported. */
+    private class Failure(val code: String, message: String, val report: String? = null) : Exception(message)
 
     private class ReleaseFile(val path: String, val sha256: String, val size: Long)
 
-    private class Release(val bundle: String, val sequence: Double, val version: String, val nativeApi: String, val files: List<ReleaseFile>, val manifest: ByteArray, val signature: String)
+    /** [envelope]: as downloaded, kept next to the bundle for the shell's check at every launch. */
+    private class Release(
+        val bundle: String, val sequence: Double, val version: String, val nativeApi: String, val files: List<ReleaseFile>,
+        val keyId: String, val revokeKeys: List<String>, val resetSequence: Boolean, val envelope: ByteArray,
+    )
 
     /** What the worker needs from the main thread, read once per call. */
-    private class Snapshot(val config: AkanNativeUpdateConfig, val running: Double, val failed: List<String>, val pending: String?, val activeRoot: File?)
+    private class Snapshot(
+        val config: AkanNativeUpdateConfig, val running: Pair<Double, String>?, val failed: List<String>, val pending: String?,
+        val activeRoot: File?, val revoked: List<String>,
+    )
 
     private fun snapshot(config: AkanNativeUpdateConfig): Snapshot {
         val state = AkanNativeUpdates.readState()
         val active = AkanNativeUpdates.active
-        return Snapshot(config, active?.sequence ?: config.embeddedSequence, state.failed.toList(), state.pending?.bundle, active?.let { AkanNativeUpdates.bundleDirectory(it.bundle) })
+        return Snapshot(
+            config, active?.let { it.sequence to it.keyId }, state.failed.toList(), state.pending?.bundle,
+            active?.let { AkanNativeUpdates.bundleDirectory(it.bundle) }, state.revokedKeys.toList(),
+        )
     }
 
     private fun <T> configured(reply: AkanNativeReply<T>): AkanNativeUpdateConfig? {
@@ -72,7 +87,7 @@ class UpdatesPlugin(private val context: AkanNativePluginContext) : UpdatesPlugi
         val config = configured(reply) ?: return
         val snap = snapshot(config)
         worker(reply) {
-            val release = fetchRelease(config)
+            val release = fetchRelease(config, snap)
             val available = isNewer(release, snap)
             val size = if (available) release.files.filter { localCopy(it, snap) == null }.sumOf { it.size }.toDouble() else null
             reply.resolve(UpdatesUpdateCheck(available = available, bundle = release.bundle, version = release.version, sequence = release.sequence, downloadSize = size))
@@ -88,11 +103,11 @@ class UpdatesPlugin(private val context: AkanNativePluginContext) : UpdatesPlugi
         download = reply.call
         val snap = snapshot(config)
         worker(reply, done = { downloading = false; download = null }) {
-            val release = fetchRelease(config)
+            val release = fetchRelease(config, snap)
             if (!isNewer(release, snap)) throw Failure(AkanNativeErrorCode.NOT_FOUND, "no newer release for this app (native API ${config.nativeApi})")
             if (snap.pending != release.bundle) {
                 install(release, config, snap)
-                main.post { AkanNativeUpdates.stage(AkanNativeUpdateEntry(release.bundle, release.sequence, release.nativeApi)) }
+                main.post { AkanNativeUpdates.stage(AkanNativeUpdateEntry(release.bundle, release.sequence, release.nativeApi, release.keyId)) }
             }
             reply.resolve(UpdatesDownloadResult(bundle = release.bundle))
         }
@@ -133,9 +148,30 @@ class UpdatesPlugin(private val context: AkanNativePluginContext) : UpdatesPlugi
         }.start()
     }
 
-    /** Newer than what runs (and than the APK's own bundle), for this binary, not rolled back before. */
-    private fun isNewer(release: Release, snap: Snapshot): Boolean =
-        release.nativeApi == snap.config.nativeApi && release.sequence > maxOf(snap.running, snap.config.embeddedSequence) && release.bundle !in snap.failed
+    /**
+     * Newer than what runs (and than the APK's own bundle), not rolled back before. A manifest's revocations are
+     * recorded whether or not its release is newer: the key behind a bad release must stop counting either way.
+     */
+    private fun isNewer(release: Release, snap: Snapshot): Boolean {
+        val decision = AkanNativeKernel.updateDecision(
+            snap.config.ring, snap.revoked, release.keyId, release.revokeKeys, release.resetSequence,
+            release.sequence, snap.config.embeddedSequence, snap.running,
+        )
+        return when (decision.kind) {
+            AkanNativeUpdateDecision.Kind.TAKE, AkanNativeUpdateDecision.Kind.STALE -> {
+                if (decision.revoke.isNotEmpty()) main.post { AkanNativeUpdates.revoke(decision.revoke) }
+                decision.kind == AkanNativeUpdateDecision.Kind.TAKE && release.bundle !in snap.failed
+            }
+            AkanNativeUpdateDecision.Kind.UNTRUSTED, AkanNativeUpdateDecision.Kind.REVOKED -> {
+                reportFailed(release.bundle, release.sequence, "signature")
+                throw Failure(AkanNativeErrorCode.INTERNAL, "the release is signed by key ${release.keyId}, which this app does not trust")
+            }
+            else -> {
+                reportFailed(release.bundle, release.sequence, "manifest")
+                throw Failure(AkanNativeErrorCode.INTERNAL, "invalid release manifest: key ${release.keyId} may not revoke ${release.revokeKeys.joinToString(", ")}")
+            }
+        }
+    }
 
     private fun base(config: AkanNativeUpdateConfig) = "${config.url}/${config.platform}"
 
@@ -151,6 +187,9 @@ class UpdatesPlugin(private val context: AkanNativePluginContext) : UpdatesPlugi
             connection.readTimeout = 30_000
             connection.useCaches = false
             connection.setRequestProperty("Cache-Control", "no-cache")
+            // HttpURLConnection asks for text/html first, and a CDN that injects scripts into HTML responses
+            // (Cloudflare Web Analytics) changes the signed bytes.
+            connection.setRequestProperty("Accept", "*/*")
             val status = connection.responseCode
             if (status == 404) throw Failure(AkanNativeErrorCode.NOT_FOUND, "$url not found")
             if (status != 200) throw Failure(AkanNativeErrorCode.INTERNAL, "$url: HTTP $status")
@@ -179,31 +218,57 @@ class UpdatesPlugin(private val context: AkanNativePluginContext) : UpdatesPlugi
         return out.toByteArray()
     }
 
-    private fun fetchRelease(config: AkanNativeUpdateConfig): Release {
-        val manifestUrl = "${base(config)}/${config.channel}.json"
-        val manifest = fetch(manifestUrl, 1L shl 20)
-        val signatureText = String(fetch("$manifestUrl.sig", 1024)).trim()
-        val signature = try {
-            Base64.getDecoder().decode(signatureText)
-        } catch (e: IllegalArgumentException) {
-            throw Failure(AkanNativeErrorCode.INTERNAL, "the release signature is not base64")
+    private fun fetchRelease(config: AkanNativeUpdateConfig, snap: Snapshot): Release {
+        val url = AkanNativeKernel.updateManifestUrl(config.url, config.platform, config.channel, config.nativeApi)
+        // A 1 MiB manifest is 1.4 MiB in base64.
+        val data = fetch(url, 3L shl 19)
+        val envelope = AkanNativeUpdateEnvelope.open(data, config, snap.revoked)
+        if (envelope == null) {
+            reportRefused(data, "signature")
+            throw Failure(AkanNativeErrorCode.INTERNAL, "the release is not signed by a key of updates.publicKeys this app still trusts")
+        }
+        return try {
+            parse(envelope, data, config)
+        } catch (f: Failure) {
+            reportRefused(data, "manifest")
+            throw f
         }
-        if (!AkanNativeUpdates.signed(manifest, signature, config.publicKey)) throw Failure(AkanNativeErrorCode.INTERNAL, "the release signature does not match updates.publicKey")
-        return parse(manifest, signatureText, config)
+    }
+
+    private fun reportFailed(bundle: String?, sequence: Double?, reason: String) {
+        main.post { AkanNativeUpdateReports.record("failed", bundle, sequence, reason) }
+    }
+
+    /**
+     * The release a refused envelope names, read without trusting it and only to say which release failed: a forged
+     * name can at worst count against a release the server already published for this app.
+     */
+    private fun reportRefused(raw: ByteArray, reason: String) {
+        val manifest = try {
+            JSONObject(String(android.util.Base64.decode(JSONObject(String(raw)).getString("manifest"), android.util.Base64.DEFAULT)))
+        } catch (e: Exception) {
+            null
+        }
+        reportFailed(manifest?.optString("bundle"), manifest?.optDouble("sequence")?.takeIf { it.isFinite() }, reason)
     }
 
     /** Checks every field of the (signed) manifest before any of it is used. */
-    private fun parse(data: ByteArray, signature: String, config: AkanNativeUpdateConfig): Release {
+    private fun parse(envelope: AkanNativeUpdateEnvelope, raw: ByteArray, config: AkanNativeUpdateConfig): Release {
         fun bad(why: String) = Failure(AkanNativeErrorCode.INTERNAL, "invalid release manifest: $why")
         val o = try {
-            JSONObject(String(data))
+            JSONObject(String(envelope.manifest))
         } catch (e: Exception) {
             throw bad("not a JSON object")
         }
-        if (o.optInt("schema") != 1 || o.optString("kind") != "web") throw bad("schema 1, kind web expected")
-        if (o.optString("app") != config.app || o.optString("platform") != config.platform || o.optString("channel") != config.channel) {
-            throw bad("made for another app, platform or channel")
+        if (o.optInt("schema") != 2 || o.optString("kind") != "web") throw bad("schema 2, kind web expected")
+        if (o.optString("app") != config.app || o.optString("platform") != config.platform || o.optString("channel") != config.channel ||
+            o.optString("nativeApi") != config.nativeApi) {
+            throw bad("made for another app, platform, channel or native API")
         }
+        val revokeList = if (o.has("revokeKeys")) o.optJSONArray("revokeKeys") ?: throw bad("revokeKeys") else null
+        val revokeKeys = List(revokeList?.length() ?: 0) { revokeList?.opt(it) as? String ?: throw bad("revokeKeys") }
+        if (revokeKeys.size > 16 || !revokeKeys.all(AkanNativeKernel::isUpdateKeyId)) throw bad("revokeKeys")
+        if (o.has("resetSequence") && o.opt("resetSequence") !is Boolean) throw bad("resetSequence")
         val bundle = o.optString("bundle")
         if (!AkanNativeUpdates.isBundleId(bundle)) throw bad("bundle id")
         val sequence = o.optDouble("sequence", -1.0)
@@ -219,7 +284,10 @@ class UpdatesPlugin(private val context: AkanNativePluginContext) : UpdatesPlugi
             ReleaseFile(path, sha, size)
         }
         if (files.sumOf { it.size } > 300_000_000 || files.none { it.path == "index.html" } || files.map { it.path }.toSet().size != files.size) throw bad("files")
-        return Release(bundle, sequence, o.optString("version"), o.optString("nativeApi"), files, data, signature)
+        return Release(
+            bundle, sequence, o.optString("version"), o.optString("nativeApi"), files,
+            envelope.keyId, revokeKeys, o.optBoolean("resetSequence"), raw,
+        )
     }
 
     /** Relative, "/"-separated, no empty, "." or ".." segments. */
@@ -243,8 +311,23 @@ class UpdatesPlugin(private val context: AkanNativePluginContext) : UpdatesPlugi
         return if (data.size.toLong() == file.size && hex(data) == file.sha256) data else null
     }
 
-    /** Downloads into bundles/<bundle>.partial, verifies each file, then renames it into place. */
+    /**
+     * Downloads into bundles/<bundle>.partial, verifies each file, then renames it into place. A failure is reported
+     * under its reason, and an IOException outside a download is the disk's.
+     */
     private fun install(release: Release, config: AkanNativeUpdateConfig, snap: Snapshot) {
+        try {
+            place(release, config, snap)
+        } catch (f: Failure) {
+            f.report?.let { reportFailed(release.bundle, release.sequence, it) }
+            throw f
+        } catch (e: IOException) {
+            reportFailed(release.bundle, release.sequence, "disk")
+            throw e
+        }
+    }
+
+    private fun place(release: Release, config: AkanNativeUpdateConfig, snap: Snapshot) {
         val target = AkanNativeUpdates.bundleDirectory(release.bundle)
         val staging = File(target.parentFile, "${release.bundle}.partial")
         staging.deleteRecursively()
@@ -262,29 +345,38 @@ class UpdatesPlugin(private val context: AkanNativePluginContext) : UpdatesPlugi
                 val digest = MessageDigest.getInstance("SHA-256")
                 var size = 0L
                 destination.outputStream().use { out ->
-                    fetch("${base(config)}/files/${file.sha256}", file.size) { buffer, n ->
-                        digest.update(buffer, 0, n)
-                        out.write(buffer, 0, n)
-                        size += n
+                    try {
+                        fetch("${base(config)}/files/${file.sha256}", file.size) { buffer, n ->
+                            digest.update(buffer, 0, n)
+                            try {
+                                out.write(buffer, 0, n)
+                            } catch (e: IOException) {
+                                throw Failure(AkanNativeErrorCode.INTERNAL, "cannot write ${file.path}: ${e.message ?: e}", "disk")
+                            }
+                            size += n
+                        }
+                    } catch (f: Failure) {
+                        throw if (f.report != null || f.code == AkanNativeErrorCode.CANCELLED) f else Failure(f.code, f.message ?: "download failed", "download")
+                    } catch (e: IOException) {
+                        throw Failure(AkanNativeErrorCode.INTERNAL, "${file.path}: ${e.message ?: e}", "download")
                     }
                 }
                 if (size != file.size || digest.digest().joinToString("") { "%02x".format(it) } != file.sha256) {
                     staging.deleteRecursively()
-                    throw Failure(AkanNativeErrorCode.INTERNAL, "${file.path} does not match its hash")
+                    throw Failure(AkanNativeErrorCode.INTERNAL, "${file.path} does not match its hash", "verify")
                 }
             }
             received += file.size
             val progress = UpdatesUpdateProgress(received = received.toDouble(), total = total)
             main.post { events.progress(progress) }
         }
-        // The shell checks the signed manifest against the files at every launch (AkanNativeUpdates.verified).
-        File(staging, "manifest.json").writeBytes(release.manifest)
-        File(staging, "manifest.json.sig").writeText(release.signature)
+        // The shell checks the envelope against the files at every launch (AkanNativeUpdates.verified).
+        File(staging, "manifest.signed.json").writeBytes(release.envelope)
         if (release.files.any { File(staging, it.path).length() != it.size }) {
             staging.deleteRecursively()
-            throw Failure(AkanNativeErrorCode.INTERNAL, "the downloaded bundle is incomplete")
+            throw Failure(AkanNativeErrorCode.INTERNAL, "the downloaded bundle is incomplete", "verify")
         }
         target.deleteRecursively()
-        if (!staging.renameTo(target)) throw Failure(AkanNativeErrorCode.INTERNAL, "could not move the downloaded bundle into place")
+        if (!staging.renameTo(target)) throw Failure(AkanNativeErrorCode.INTERNAL, "could not move the downloaded bundle into place", "disk")
     }
 }

package/vendor/@akanjs/native/plugins/updates/ios/UpdatesPlugin.swift

@@ -1,9 +1,10 @@
 import CryptoKit
 import Foundation
 
-/// Web bundle updates (UP-2). The manifest `<url>/ios/<channel>.json` is signed as a whole
-/// (`.sig`: base64 Ed25519 over its bytes, key from akan-native.config.ts `updates.publicKey`), so every
-/// field below is trusted only after `isValidSignature`. Files are content-addressed
+/// Web bundle updates (UP-2, protocol v2). The envelope `<url>/ios/<channel>/<nativeApi>.json` holds the manifest's
+/// bytes, the keyId of the key that signed them (one of akan-native.config.ts `updates.publicKeys`) and the Ed25519
+/// signature, so every field below is trusted only after `AkanNativeUpdateEnvelope.open`. Revocations and the
+/// sequence rule are AkanNativeKernel.updateDecision, shared with Android and kernel.ts. Files are content-addressed
 /// (`<url>/ios/files/<sha256>`) and each one is checked against its hash; files the running
 /// bundle already has are copied instead of downloaded. Which bundle runs, and the trial /
 /// rollback rules, live in the shell (native/ios/Sources/AkanNativeUpdates.swift).
@@ -24,6 +25,8 @@ final class UpdatesPlugin: UpdatesPluginSpec {
     struct Failure: Error {
         let code: AkanNativeErrorCode
         let message: String
+        /// The reason a failed download is reported under (AkanNativeUpdateReports), nil when it is not reported.
+        var report: String? = nil
     }
 
     struct ReleaseFile: Sendable {
@@ -38,9 +41,11 @@ final class UpdatesPlugin: UpdatesPluginSpec {
         let version: String
         let nativeApi: String
         let files: [ReleaseFile]
-        let manifest: Data
-        /// The manifest's `.sig` as downloaded (base64), kept next to the bundle.
-        let signature: String
+        let keyId: String
+        let revokeKeys: [String]
+        let resetSequence: Bool
+        /// The envelope as downloaded, kept next to the bundle for the shell's check at every launch.
+        let envelope: Data
     }
 
     private func configured<T>(_ reply: AkanNativeReply<T>) -> AkanNativeUpdateConfig? {
@@ -68,7 +73,7 @@ final class UpdatesPlugin: UpdatesPluginSpec {
         Task {
             do {
                 let release = try await Self.fetchRelease(config)
-                let available = isNewer(release, config)
+                let available = try isNewer(release, config)
                 reply.resolve(UpdatesUpdateCheck(
                     available: available,
                     bundle: release.bundle,
@@ -94,7 +99,7 @@ final class UpdatesPlugin: UpdatesPluginSpec {
             defer { downloading = false }
             do {
                 let release = try await Self.fetchRelease(config)
-                guard isNewer(release, config) else { throw Failure(code: .notFound, message: "no newer release for this app (native API \(config.nativeApi))") }
+                guard try isNewer(release, config) else { throw Failure(code: .notFound, message: "no newer release for this app (native API \(config.nativeApi))") }
                 if AkanNativeUpdates.readState().pending?.bundle != release.bundle { try await install(release, config) }
                 reply.resolve(UpdatesDownloadResult(bundle: release.bundle))
             } catch let f as Failure {
@@ -128,16 +133,33 @@ final class UpdatesPlugin: UpdatesPluginSpec {
 
     // MARK: releases
 
-    /// Newer than what runs (and than the app's own bundle), for this binary, not rolled back before.
-    private func isNewer(_ release: Release, _ config: AkanNativeUpdateConfig) -> Bool {
-        let running = AkanNativeUpdates.active?.sequence ?? config.embeddedSequence
-        return release.nativeApi == config.nativeApi && release.sequence > max(running, config.embeddedSequence)
-            && !AkanNativeUpdates.readState().failed.contains(release.bundle)
+    /// Newer than what runs (and than the app's own bundle), not rolled back before. A manifest's revocations are
+    /// recorded whether or not its release is newer: the key behind a bad release must stop counting either way.
+    private func isNewer(_ release: Release, _ config: AkanNativeUpdateConfig) throws -> Bool {
+        let state = AkanNativeUpdates.readState()
+        let decision = AkanNativeKernel.updateDecision(
+            ring: config.ring, revoked: state.revokedKeys, signer: release.keyId, revokeKeys: release.revokeKeys,
+            resetSequence: release.resetSequence, sequence: release.sequence, embedded: config.embeddedSequence,
+            running: AkanNativeUpdates.active.map { (sequence: $0.sequence, keyId: $0.keyId) }
+        )
+        switch decision.kind {
+        case .take, .stale:
+            if !decision.revoke.isEmpty { AkanNativeUpdates.revoke(decision.revoke) }
+            return decision.kind == .take && !state.failed.contains(release.bundle)
+        case .untrusted, .revoked:
+            AkanNativeUpdateReports.record("failed", bundle: release.bundle, sequence: release.sequence, reason: "signature")
+            throw Failure(code: .internalError, message: "the release is signed by key \(release.keyId), which this app does not trust")
+        case .selfRevoke, .revokeLater:
+            AkanNativeUpdateReports.record("failed", bundle: release.bundle, sequence: release.sequence, reason: "manifest")
+            throw Failure(code: .internalError, message: "invalid release manifest: key \(release.keyId) may not revoke \(release.revokeKeys.joined(separator: ", "))")
+        }
     }
 
     private static func request(_ url: URL) -> URLRequest {
         var request = URLRequest(url: url, cachePolicy: .reloadIgnoringLocalAndRemoteCacheData, timeoutInterval: 30)
         request.setValue("no-cache", forHTTPHeaderField: "Cache-Control")
+        //? Not text/html: a CDN that injects scripts into HTML responses (Cloudflare Web Analytics) would change signed bytes.
+        request.setValue("*/*", forHTTPHeaderField: "Accept")
         return request
     }
 
@@ -187,27 +209,45 @@ final class UpdatesPlugin: UpdatesPluginSpec {
     private static func base(_ config: AkanNativeUpdateConfig) -> String { "\(config.url)/\(config.platform)" }
 
     private static func fetchRelease(_ config: AkanNativeUpdateConfig) async throws -> Release {
-        guard let manifestURL = URL(string: "\(base(config))/\(config.channel).json"), let sigURL = URL(string: "\(base(config))/\(config.channel).json.sig") else {
-            throw Failure(code: .internalError, message: "bad updates.url \(config.url)")
+        let address = AkanNativeKernel.updateManifestURL(config.url, platform: config.platform, channel: config.channel, nativeApi: config.nativeApi)
+        guard let url = URL(string: address) else { throw Failure(code: .internalError, message: "bad updates.url \(config.url)") }
+        //? A 1 MiB manifest is 1.4 MiB in base64.
+        let data = try await fetch(url, limit: 3 << 19)
+        guard let envelope = AkanNativeUpdateEnvelope.open(data, config, revoked: AkanNativeUpdates.readState().revokedKeys) else {
+            reportRefused(data, "signature")
+            throw Failure(code: .internalError, message: "the release is not signed by a key of updates.publicKeys this app still trusts")
         }
-        let manifest = try await fetch(manifestURL, limit: 1 << 20)
-        let sigText = String(decoding: try await fetch(sigURL, limit: 1024), as: UTF8.self).trimmingCharacters(in: .whitespacesAndNewlines)
-        guard let signature = Data(base64Encoded: sigText),
-              let key = try? Curve25519.Signing.PublicKey(rawRepresentation: config.publicKey),
-              key.isValidSignature(signature, for: manifest) else {
-            throw Failure(code: .internalError, message: "the release signature does not match updates.publicKey")
+        do {
+            return try parse(envelope, data, config)
+        } catch {
+            reportRefused(data, "manifest")
+            throw error
         }
-        return try parse(manifest, sigText, config)
+    }
+
+    /// The release a refused envelope names, read without trusting it and only to say which release failed: a forged
+    /// name can at worst count against a release the server already published for this app.
+    private static func reportRefused(_ raw: Data, _ reason: String) {
+        let envelope = (try? JSONSerialization.jsonObject(with: raw)) as? [String: Any]
+        let manifest = (envelope?["manifest"] as? String).flatMap { Data(base64Encoded: $0) }
+            .flatMap { (try? JSONSerialization.jsonObject(with: $0)) as? [String: Any] }
+        AkanNativeUpdateReports.record(
+            "failed", bundle: manifest?["bundle"] as? String, sequence: (manifest?["sequence"] as? NSNumber)?.doubleValue, reason: reason
+        )
     }
 
     /// Checks every field of the (signed) manifest before any of it is used.
-    private static func parse(_ data: Data, _ signature: String, _ config: AkanNativeUpdateConfig) throws -> Release {
+    private static func parse(_ envelope: AkanNativeUpdateEnvelope, _ raw: Data, _ config: AkanNativeUpdateConfig) throws -> Release {
         let bad = { (why: String) in Failure(code: .internalError, message: "invalid release manifest: \(why)") }
-        guard let o = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { throw bad("not a JSON object") }
-        guard (o["schema"] as? NSNumber)?.intValue == 1, o["kind"] as? String == "web" else { throw bad("schema 1, kind web expected") }
-        guard o["app"] as? String == config.app, o["platform"] as? String == config.platform, o["channel"] as? String == config.channel else {
-            throw bad("made for another app, platform or channel")
+        guard let o = try? JSONSerialization.jsonObject(with: envelope.manifest) as? [String: Any] else { throw bad("not a JSON object") }
+        guard (o["schema"] as? NSNumber)?.intValue == 2, o["kind"] as? String == "web" else { throw bad("schema 2, kind web expected") }
+        guard o["app"] as? String == config.app, o["platform"] as? String == config.platform, o["channel"] as? String == config.channel,
+              o["nativeApi"] as? String == config.nativeApi else {
+            throw bad("made for another app, platform, channel or native API")
         }
+        let revokeKeys = o["revokeKeys"] as? [String] ?? []
+        guard o["revokeKeys"] == nil || o["revokeKeys"] is [String], revokeKeys.count <= 16, revokeKeys.allSatisfy(AkanNativeKernel.isUpdateKeyId),
+              o["resetSequence"] == nil || o["resetSequence"] is Bool else { throw bad("revokeKeys or resetSequence") }
         guard let bundle = o["bundle"] as? String, AkanNativeUpdates.isBundleId(bundle) else { throw bad("bundle id") }
         guard let sequence = (o["sequence"] as? NSNumber)?.doubleValue, sequence.isFinite, sequence > 0 else { throw bad("sequence") }
         guard let nativeApi = o["nativeApi"] as? String, let list = o["files"] as? [[String: Any]], (1...5000).contains(list.count) else { throw bad("nativeApi or files") }
@@ -220,7 +260,10 @@ final class UpdatesPlugin: UpdatesPluginSpec {
             files.append(ReleaseFile(path: path, sha256: sha.lowercased(), size: size))
         }
         guard total <= 300_000_000, files.contains(where: { $0.path == "index.html" }), Set(files.map(\.path)).count == files.count else { throw bad("files") }
-        return Release(bundle: bundle, sequence: sequence, version: o["version"] as? String ?? "", nativeApi: nativeApi, files: files, manifest: data, signature: signature)
+        return Release(
+            bundle: bundle, sequence: sequence, version: o["version"] as? String ?? "", nativeApi: nativeApi, files: files,
+            keyId: envelope.keyId, revokeKeys: revokeKeys, resetSequence: o["resetSequence"] as? Bool ?? false, envelope: raw
+        )
     }
 
     /// Relative, "/"-separated, no empty, "." or ".." segments.
@@ -247,8 +290,23 @@ final class UpdatesPlugin: UpdatesPluginSpec {
         return localHashes[key] == file.sha256 ? candidate : nil
     }
 
-    /// Downloads into bundles/<bundle>.partial, verifies each file, then renames and stages it.
+    /// Downloads into bundles/<bundle>.partial, verifies each file, then renames and stages it. A failure is reported
+    /// under its reason, and an error that is neither a download's nor a cancellation is the disk's.
     private func install(_ release: Release, _ config: AkanNativeUpdateConfig) async throws {
+        do {
+            try await place(release, config)
+        } catch {
+            let reason = (error as? Failure).map(\.report) ?? (Self.cancelled(error) ? nil : "disk")
+            if let reason { AkanNativeUpdateReports.record("failed", bundle: release.bundle, sequence: release.sequence, reason: reason) }
+            throw error
+        }
+    }
+
+    private static func cancelled(_ error: Error) -> Bool {
+        error is CancellationError || (error as? URLError)?.code == .cancelled
+    }
+
+    private func place(_ release: Release, _ config: AkanNativeUpdateConfig) async throws {
         let fm = FileManager.default
         let target = AkanNativeUpdates.bundleDirectory(release.bundle)
         let staging = target.deletingLastPathComponent().appendingPathComponent("\(release.bundle).partial", isDirectory: true)
@@ -264,29 +322,36 @@ final class UpdatesPlugin: UpdatesPluginSpec {
                 try fm.copyItem(at: local, to: destination)
             } else {
                 guard let url = URL(string: "\(Self.base(config))/files/\(file.sha256)") else { throw Failure(code: .internalError, message: "bad file URL") }
-                let downloaded = try await Self.download(url, size: file.size)
+                let downloaded: URL
+                do {
+                    downloaded = try await Self.download(url, size: file.size)
+                } catch let failure as Failure {
+                    throw Failure(code: failure.code, message: failure.message, report: "download")
+                } catch {
+                    if Self.cancelled(error) { throw error }
+                    throw Failure(code: .internalError, message: "\(file.path): \(error.localizedDescription)", report: "download")
+                }
                 guard (try? Self.hex(file: downloaded)) == file.sha256 else {
                     try? fm.removeItem(at: downloaded)
                     try? fm.removeItem(at: staging)
-                    throw Failure(code: .internalError, message: "\(file.path) does not match its hash")
+                    throw Failure(code: .internalError, message: "\(file.path) does not match its hash", report: "verify")
                 }
                 try fm.moveItem(at: downloaded, to: destination)
             }
             received += file.size
             events.progress(UpdatesUpdateProgress(received: Double(received), total: Double(total)))
         }
-        // The shell checks the signed manifest against the files at every launch (AkanNativeUpdates.verified).
-        try release.manifest.write(to: staging.appendingPathComponent("manifest.json"))
-        try Data(release.signature.utf8).write(to: staging.appendingPathComponent("manifest.json.sig"))
+        // The shell checks the envelope against the files at every launch (AkanNativeUpdates.verified).
+        try release.envelope.write(to: staging.appendingPathComponent("manifest.signed.json"))
         let complete = release.files.allSatisfy { file in
             (try? fm.attributesOfItem(atPath: staging.appendingPathComponent(file.path).path)[.size] as? NSNumber)?.intValue == file.size
         }
         guard complete else {
             try? fm.removeItem(at: staging)
-            throw Failure(code: .internalError, message: "the downloaded bundle is incomplete")
+            throw Failure(code: .internalError, message: "the downloaded bundle is incomplete", report: "verify")
         }
         if fm.fileExists(atPath: target.path) { try fm.removeItem(at: target) }
         try fm.moveItem(at: staging, to: target)
-        AkanNativeUpdates.stage(AkanNativeUpdateEntry(bundle: release.bundle, sequence: release.sequence, nativeApi: release.nativeApi))
+        AkanNativeUpdates.stage(AkanNativeUpdateEntry(bundle: release.bundle, sequence: release.sequence, nativeApi: release.nativeApi, keyId: release.keyId))
     }
 }

package/vendor/@akanjs/native/plugins/updates/native-plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "updates",
   "apiVersion": 1,
-  "methods": ["getState", "check", "download", "apply", "notifyReady", "reset"],
+  "methods": ["getState", "check", "download", "apply", "notifyReady", "reset", "setChannel"],
   "events": ["progress"],
   "coalesce": ["progress"],
   "codegen": true,
@@ -10,10 +10,12 @@
   "ios": {
     "sources": ["ios/*.swift"],
     "class": "UpdatesPlugin",
+    "methods": ["getState", "check", "download", "apply", "notifyReady", "reset"],
     "frameworks": ["CryptoKit"]
   },
   "android": {
     "sources": ["android/*.kt"],
-    "class": "com.akanjs.plugins.updates.UpdatesPlugin"
+    "class": "com.akanjs.plugins.updates.UpdatesPlugin",
+    "methods": ["getState", "check", "download", "apply", "notifyReady", "reset"]
   }
 }

package/vendor/@akanjs/native/plugins/updates/src/desktop.ts

@@ -78,6 +78,8 @@ interface State {
   rollback?: { build: number; previous: string; to: string; attempts: number };
   /** embeddedSequence of the build installed here: another one means the app was installed again. */
   installed?: number;
+  /** setChannel(): the manifest read over updates.json's `channel`. */
+  channel?: string;
 }
 
 interface Manifest {
@@ -269,7 +271,8 @@ export function createDesktopUpdates(options: DesktopUpdatesOptions = {}): Deskt
         "UNSUPPORTED",
         "updates are not configured (akan-native.config.ts `updates`, a built app)",
       );
-    return config;
+    const { channel } = readState();
+    return channel ? { ...config, channel } : config;
   };
   /** `entry` when the running app is that release (installed by an update), not another build. */
   const ifRunning = <E extends Entry>(entry: E | undefined): E | undefined =>
@@ -848,6 +851,17 @@ export function createDesktopUpdates(options: DesktopUpdatesOptions = {}): Deskt
         if (windows) void recordInstalledVersion(c.app, installed, entry.version);
       },
 
+      async setChannel(args) {
+        need();
+        const channel = (args as { channel?: unknown } | undefined)?.channel ?? null;
+        if (channel !== null && (typeof channel !== "string" || !/^[a-z0-9][a-z0-9._-]{0,63}$/i.test(channel)))
+          throw new AkanNativeError("INVALID_ARGS", "channel must be a manifest name (letters, digits, . _ -) or null");
+        const state = readState();
+        if (channel === null) delete state.channel;
+        else state.channel = channel;
+        writeState(state);
+      },
+
       async reset() {
         need();
         const state = readState();

package/vendor/@akanjs/native/plugins/updates/src/index.ts

@@ -67,6 +67,12 @@ export interface UpdatesApi {
    * releases; the running app stays, and a trial keeps its record.
    */
   reset(): Promise<void>;
+  /**
+   * Desktop: the manifest this app reads from now on, over the built `updates.channel` until set back with `null` —
+   * a server that moves this device between a pilot and a stable channel. A release older than the running one is
+   * never taken, so a device leaving a pilot channel stays on its pilot build until the other channel passes it.
+   */
+  setChannel(args: { channel: string | null }): Promise<void>;
 }
 
 export interface UpdatesEvents {
@@ -74,7 +80,7 @@ export interface UpdatesEvents {
 }
 
 export const updates = definePlugin<UpdatesApi, UpdatesEvents>("updates", {
-  methods: ["getState", "check", "download", "apply", "notifyReady", "reset"],
+  methods: ["getState", "check", "download", "apply", "notifyReady", "reset", "setChannel"],
   events: ["progress"],
 });
 

package/vendor/@akanjs/native/plugins/window/native-plugin.json

@@ -13,6 +13,10 @@
     "restore",
     "setFullscreen",
     "setAlwaysOnTop",
+    "setDecorations",
+    "setCursorVisible",
+    "setMinSize",
+    "placeOnDisplay",
     "show",
     "hide",
     "focus",