@rovq/react-native 0.0.0-stage → 0.2.0

package/android/src/main/java/com/rovq/engine/SafePackageExtractor.kt

@@ -0,0 +1,121 @@
+package com.rovq.engine
+
+import java.io.File
+import java.io.FileOutputStream
+import java.io.IOException
+import java.util.zip.ZipEntry
+import java.util.zip.ZipException
+import java.util.zip.ZipFile
+
+private const val BUFFER_SIZE = 64 * 1024
+
+/**
+ * Extracts a package without trusting it, even though its signature was already
+ * verified. If a signing key ever leaks, this keeps an attacker inside the package
+ * folder, so the files of the app itself stay out of reach.
+ */
+internal class SafePackageExtractor {
+
+    /** @param destination an empty folder that only this extraction uses. */
+    fun extract(packageFile: File, destination: File) {
+        val root = destination.canonicalPath + File.separator
+        ZipStructureCheck.check(packageFile)
+        try {
+            // ZipFile reads names from the central directory, the same source the server
+            // checked. Local file headers could hold different names.
+            ZipFile(packageFile).use { zip ->
+                extractEntries(zip, destination, root)
+            }
+        } catch (error: ZipException) {
+            throw invalid("Not a readable ZIP file", error)
+        } catch (error: IllegalArgumentException) {
+            // Android rejects some malformed names with this exception.
+            throw invalid("The ZIP file has a malformed entry", error)
+        } catch (error: IllegalStateException) {
+            throw invalid("The ZIP file could not be read", error)
+        }
+    }
+
+    private fun extractEntries(zip: ZipFile, destination: File, root: String) {
+        val seen = HashSet<String>()
+        var hasBundle = false
+        var count = 0
+        var totalSize = 0L
+
+        val entries = zip.entries()
+        while (entries.hasMoreElements()) {
+            val entry = entries.nextElement()
+            count += 1
+            if (count > PackageRules.MAX_ENTRIES) throw invalid("Too many files")
+            if (entry.isDirectory) throw invalid("Folder entries are not allowed")
+
+            val name = entry.name
+            PackageRules.findPathProblem(name)?.let { throw invalid("The file $name $it") }
+            if (!seen.add(PackageRules.pathIdentity(name))) {
+                throw invalid("The file $name appears more than once")
+            }
+
+            val target = File(destination, name)
+            // A second, independent check: whatever the rules allow, the real path must
+            // stay inside the folder.
+            if (!target.canonicalPath.startsWith(root)) throw invalid("The file $name leaves the folder")
+
+            val written = writeEntry(zip, entry, target, PackageRules.MAX_TOTAL_SIZE - totalSize)
+            totalSize += written
+            if (name == PackageRules.BUNDLE_FILE_NAME) {
+                if (written == 0L) throw invalid("The bundle file is empty")
+                hasBundle = true
+            }
+        }
+        if (!hasBundle) throw invalid("The bundle file is missing")
+    }
+
+    /** Counts real bytes, because a ZIP file can lie about how large its contents are. */
+    private fun writeEntry(zip: ZipFile, entry: ZipEntry, target: File, allowance: Long): Long {
+        target.parentFile?.let { parent ->
+            if (!parent.isDirectory && !parent.mkdirs()) {
+                throw RovqException(RovqErrorCode.STORAGE_FAILED, "Could not create ${parent.name}")
+            }
+        }
+        var written = 0L
+        val input = try {
+            zip.getInputStream(entry)
+        } catch (error: ZipException) {
+            throw invalid("Could not read ${entry.name}", error)
+        }
+        input.use { source ->
+            val output = try {
+                FileOutputStream(target)
+            } catch (error: IOException) {
+                throw RovqException(RovqErrorCode.STORAGE_FAILED, "Could not create ${entry.name}", error)
+            }
+            output.use { file ->
+                val buffer = ByteArray(BUFFER_SIZE)
+                while (true) {
+                    val count = try {
+                        source.read(buffer)
+                    } catch (error: IOException) {
+                        throw invalid("Could not read ${entry.name}", error)
+                    }
+                    if (count < 0) break
+                    written += count
+                    if (written > allowance) throw invalid("The package is too large when decompressed")
+                    try {
+                        file.write(buffer, 0, count)
+                    } catch (error: IOException) {
+                        throw RovqException(RovqErrorCode.STORAGE_FAILED, "Could not write ${entry.name}", error)
+                    }
+                }
+                // Forces the bytes to disk, because the release becomes active by renaming
+                // its folder, and that rename must not outrun the data.
+                file.fd.sync()
+            }
+        }
+        // Not every ZIP reader enforces this, so a mismatch has to be checked here.
+        if (written != entry.size) throw invalid("The file ${entry.name} lies about its size")
+        return written
+    }
+
+    private fun invalid(message: String, cause: Throwable? = null) =
+        RovqException(RovqErrorCode.INVALID_PACKAGE, message, cause)
+}

package/android/src/main/java/com/rovq/engine/StrictBase64.kt

@@ -0,0 +1,37 @@
+package com.rovq.engine
+
+/**
+ * Decodes standard Base64 and accepts only one spelling of each value, as the server
+ * does. It is written here because java.util.Base64 needs API 26, android.util.Base64
+ * does not exist in unit tests, and neither of them rejects non-canonical input.
+ */
+internal object StrictBase64 {
+    private const val ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+
+    /** Returns null unless the value is valid, canonical, and decodes to this many bytes. */
+    fun decode(value: String, expectedSize: Int): ByteArray? {
+        if (value.isEmpty() || value.length % 4 != 0) return null
+        val padding = value.length - value.trimEnd('=').length
+        if (padding > 2) return null
+
+        val output = ByteArray(value.length / 4 * 3 - padding)
+        if (output.size != expectedSize) return null
+
+        var buffer = 0
+        var bits = 0
+        var written = 0
+        for (index in 0 until value.length - padding) {
+            val digit = ALPHABET.indexOf(value[index])
+            if (digit < 0) return null
+            buffer = (buffer shl 6) or digit
+            bits += 6
+            if (bits >= 8) {
+                bits -= 8
+                output[written++] = (buffer shr bits).toByte()
+                buffer = buffer and ((1 shl bits) - 1)
+            }
+        }
+        // Leftover bits must be zero, or two different strings would decode to the same bytes.
+        return if (buffer == 0) output else null
+    }
+}

package/android/src/main/java/com/rovq/engine/UpdateInstaller.kt

@@ -0,0 +1,347 @@
+package com.rovq.engine
+
+import java.io.File
+import java.io.IOException
+import java.io.InputStream
+import java.security.MessageDigest
+
+// Download links last an hour, so they are fetched a few files at a time, just before use.
+private const val LINK_BATCH_SIZE = 20
+private const val BUFFER_SIZE = 64 * 1024
+private const val EMPTY_FILE_HASH = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+
+/** What the server offered. None of this is trusted until the manifest has been verified. */
+data class OfferedUpdate(
+    val manifest: String,
+    val signature: String,
+    val keyId: String,
+    /** Only for a ZIP package. A release made of files is fetched file by file. */
+    val downloadUrl: String?,
+)
+
+/** A verified release, fully extracted in its own folder. */
+data class InstalledRelease(
+    val manifest: VerifiedManifest,
+    val folder: File,
+    val bundleFile: File,
+)
+
+/** Asks the server for download links, by hash, for files of one release. */
+fun interface FileLinks {
+    /** @throws IOException if the server cannot be reached or answers with an error. */
+    fun linksFor(releaseId: String, hashes: List<String>): Map<String, String>
+}
+
+/** The app's own copies of package files, which a release made of files can reuse. */
+fun interface BuiltInFiles {
+    /** Opens the app's copy of a package path, or returns null when it has none. */
+    fun open(path: String): InputStream?
+}
+
+/**
+ * Takes an offered update to a verified folder on disk, without activating it.
+ *
+ * Each release gets its own folder because the image cache keys on the path. Reusing a
+ * path would show old images after a reload. See docs/android-bundle-loading.md.
+ *
+ * @param rootDir a folder only the engine uses, normally inside the app's private storage.
+ * @param builtInFiles the app's own assets, which can be reused instead of downloaded.
+ */
+class UpdateInstaller(
+    rootDir: File,
+    private val verifier: ManifestVerifier,
+    private val downloader: PackageDownloader,
+    private val builtInFiles: BuiltInFiles? = null,
+) {
+    private val updatesDir = File(rootDir, "updates")
+    private val workDir = File(rootDir, "work")
+
+    // Outside the work folder, because a partial download must survive a failure or a restart.
+    private val partialDir = File(rootDir, "partial")
+    private val extractor = SafePackageExtractor()
+
+    /**
+     * @param highestSequence the highest sequence this device has accepted in this stream.
+     * @param fileLinks download links for a release made of files.
+     * @throws RovqException if any step fails. Nothing is left behind in that case.
+     */
+    @Synchronized
+    fun install(
+        offer: OfferedUpdate,
+        highestSequence: Long,
+        fileLinks: FileLinks = FileLinks { _, _ -> throw IOException("No way to fetch files") },
+        onProgress: (received: Long, total: Long) -> Unit = { _, _ -> },
+    ): InstalledRelease {
+        // Verified first, so an unsigned update causes no network traffic or disk use.
+        val manifest = verifier.verify(offer.manifest, offer.signature, offer.keyId, highestSequence)
+
+        val folder = File(updatesDir, manifest.releaseId)
+        // Folders appear only through the atomic rename below, so one that exists is complete.
+        if (!folder.isDirectory) {
+            val files = manifest.files
+            if (files != null) {
+                installFileList(files, manifest.releaseId, folder, fileLinks, onProgress)
+            } else {
+                installZip(offer, manifest, folder, onProgress)
+            }
+        }
+        return InstalledRelease(manifest, folder, File(folder, PackageRules.BUNDLE_FILE_NAME))
+    }
+
+    /** Creates an empty work folder for assembling a release, and the folders around it. */
+    private fun startWork(): File {
+        // Removes anything an earlier run left when the app was killed or the phone lost power.
+        workDir.deleteRecursively()
+        val assembled = File(workDir, "extracted")
+        if (!assembled.mkdirs() ||
+            !(updatesDir.isDirectory || updatesDir.mkdirs()) ||
+            !(partialDir.isDirectory || partialDir.mkdirs())
+        ) {
+            throw RovqException(RovqErrorCode.STORAGE_FAILED, "Could not create the engine folders")
+        }
+        return assembled
+    }
+
+    private fun moveIntoPlace(assembled: File, folder: File) {
+        if (!assembled.renameTo(folder)) {
+            throw RovqException(RovqErrorCode.STORAGE_FAILED, "Could not move the release into place")
+        }
+    }
+
+    private fun installZip(
+        offer: OfferedUpdate,
+        manifest: VerifiedManifest,
+        folder: File,
+        onProgress: (Long, Long) -> Unit,
+    ) {
+        val downloadUrl = offer.downloadUrl
+            ?: throw RovqException(RovqErrorCode.DOWNLOAD_FAILED, "The server sent no download URL")
+        val extracted = startWork()
+        val packageFile = File(partialDir, "${manifest.packageHash}.zip")
+        // Only the current offer is worth finishing.
+        partialDir.listFiles()?.filter { it != packageFile }?.forEach { it.delete() }
+        try {
+            // Extracting needs room too, and its size is unknown until then, so this asks for
+            // the package twice. A package can still expand further, and extraction reports that.
+            downloader.download(
+                downloadUrl,
+                manifest.packageHash,
+                manifest.packageSize,
+                packageFile,
+                extraSpace = manifest.packageSize,
+                onProgress = onProgress,
+            )
+            extractor.extract(packageFile, extracted)
+            moveIntoPlace(extracted, folder)
+            packageFile.delete()
+        } catch (error: RovqException) {
+            // A file that failed anything but the network is not worth continuing from.
+            if (error.code != RovqErrorCode.DOWNLOAD_FAILED) packageFile.delete()
+            throw error
+        } finally {
+            workDir.deleteRecursively()
+        }
+    }
+
+    /**
+     * Builds a release from its files: each comes from a kept release, from the app itself, or
+     * from the network, in that order, and only after its content matches the signed hash. See
+     * docs/file-packages.md.
+     */
+    private fun installFileList(
+        list: List<ManifestFile>,
+        releaseId: String,
+        folder: File,
+        fileLinks: FileLinks,
+        onProgress: (Long, Long) -> Unit,
+    ) {
+        val assembled = startWork()
+        try {
+            val wanted = list.map { it.hash }.toSet()
+            // Only the current offer is worth finishing.
+            partialDir.listFiles()?.filter { it.name !in wanted }?.forEach { it.delete() }
+            val root = assembled.canonicalPath + File.separator
+
+            // A hash already placed, so the same content at another path is linked, not fetched.
+            val placed = HashMap<String, File>()
+            // Files with no local copy at their own path. Another path may still provide them.
+            val unresolved = ArrayList<Pair<ManifestFile, File>>()
+
+            for (file in list) {
+                val target = File(assembled, file.path)
+                val parent = target.parentFile ?: assembled
+                if (!(parent.isDirectory || parent.mkdirs())) {
+                    throw RovqException(RovqErrorCode.STORAGE_FAILED, "Could not create a folder")
+                }
+                // A second, independent check: whatever the rules allow, the real path must stay
+                // inside the folder.
+                if (!(parent.canonicalPath + File.separator).startsWith(root)) {
+                    throw RovqException(RovqErrorCode.INVALID_PACKAGE, "The file ${file.path} leaves the folder")
+                }
+                val source = placed[file.hash]
+                when {
+                    source != null -> link(source, target)
+                    file.size == 0L -> {
+                        if (file.hash != EMPTY_FILE_HASH) {
+                            throw RovqException(RovqErrorCode.HASH_MISMATCH, "An empty file does not match its signed hash")
+                        }
+                        if (!target.createNewFile()) {
+                            throw RovqException(RovqErrorCode.STORAGE_FAILED, "Could not create the file")
+                        }
+                        placed[file.hash] = target
+                    }
+                    placeLocalCopy(file, target, folder) -> placed[file.hash] = target
+                    else -> unresolved += file to target
+                }
+            }
+
+            // Files to download, by hash, with every path that needs each one, in manifest order.
+            val targets = LinkedHashMap<String, MutableList<File>>()
+            val missing = ArrayList<ManifestFile>()
+            for ((file, target) in unresolved) {
+                val source = placed[file.hash]
+                when {
+                    source != null -> link(source, target)
+                    targets.containsKey(file.hash) -> targets.getValue(file.hash) += target
+                    else -> {
+                        targets[file.hash] = mutableListOf(target)
+                        missing += file
+                    }
+                }
+            }
+
+            download(missing, targets, releaseId, fileLinks, onProgress)
+            moveIntoPlace(assembled, folder)
+            // Linked into the release, so the content stays where it is needed.
+            missing.forEach { File(partialDir, it.hash).delete() }
+        } finally {
+            workDir.deleteRecursively()
+        }
+    }
+
+    private fun download(
+        missing: List<ManifestFile>,
+        targets: Map<String, List<File>>,
+        releaseId: String,
+        fileLinks: FileLinks,
+        onProgress: (Long, Long) -> Unit,
+    ) {
+        if (missing.isEmpty()) return
+        val total = missing.sumOf { it.size }
+        // Checked for the whole release first, so a full disk fails before any download.
+        val remaining = missing.sumOf { file ->
+            val partial = File(partialDir, file.hash)
+            file.size - (if (partial.isFile) minOf(partial.length(), file.size) else 0L)
+        }
+        if (downloader.freeSpaceIn(partialDir) < remaining) {
+            throw RovqException(RovqErrorCode.STORAGE_FAILED, "Not enough free space for this update")
+        }
+
+        var finished = 0L
+        onProgress(0, total)
+        for (batch in missing.chunked(LINK_BATCH_SIZE)) {
+            val links = try {
+                fileLinks.linksFor(releaseId, batch.map { it.hash })
+            } catch (error: IOException) {
+                throw RovqException(RovqErrorCode.DOWNLOAD_FAILED, error.message ?: "Could not get download links", error)
+            }
+            for (file in batch) {
+                val url = links[file.hash]
+                    ?: throw RovqException(RovqErrorCode.DOWNLOAD_FAILED, "The server sent no link for a file")
+                val partial = File(partialDir, file.hash)
+                val before = finished
+                downloader.download(url, file.hash, file.size, partial) { received, _ ->
+                    onProgress(before + received, total)
+                }
+                finished += file.size
+                targets[file.hash]?.forEach { link(partial, it) }
+            }
+        }
+    }
+
+    /**
+     * Places the same path from a kept release, or from the app itself, if its content is the
+     * signed one. Hashed every time, because reusing a damaged file would break the new release.
+     */
+    private fun placeLocalCopy(file: ManifestFile, target: File, folder: File): Boolean {
+        val kept = updatesDir.listFiles()?.filter { it.isDirectory && it.name != folder.name }.orEmpty()
+        for (release in kept) {
+            val candidate = File(release, file.path)
+            if (candidate.isFile && candidate.length() == file.size && hashOf(candidate) == file.hash) {
+                link(candidate, target)
+                return true
+            }
+        }
+        return copyBuiltIn(file, target)
+    }
+
+    /** Copies the app's own file while hashing it, and keeps the copy only if it matches. */
+    private fun copyBuiltIn(file: ManifestFile, target: File): Boolean {
+        val input = try {
+            builtInFiles?.open(file.path)
+        } catch (error: Exception) {
+            null
+        } ?: return false
+        val digest = MessageDigest.getInstance("SHA-256")
+        var copied = 0L
+        try {
+            input.use { source ->
+                target.outputStream().use { output ->
+                    val buffer = ByteArray(BUFFER_SIZE)
+                    while (true) {
+                        val count = source.read(buffer)
+                        if (count < 0) break
+                        copied += count
+                        if (copied > file.size) break
+                        digest.update(buffer, 0, count)
+                        output.write(buffer, 0, count)
+                    }
+                }
+            }
+        } catch (error: IOException) {
+            target.delete()
+            return false
+        }
+        val matches = copied == file.size && digest.digest().toHex() == file.hash
+        if (!matches) target.delete()
+        return matches
+    }
+
+    private fun hashOf(file: File): String? = try {
+        val digest = MessageDigest.getInstance("SHA-256")
+        file.inputStream().use { input ->
+            val buffer = ByteArray(BUFFER_SIZE)
+            while (true) {
+                val count = input.read(buffer)
+                if (count < 0) break
+                digest.update(buffer, 0, count)
+            }
+        }
+        digest.digest().toHex()
+    } catch (error: IOException) {
+        null
+    }
+
+    private fun ByteArray.toHex(): String = joinToString("") { "%02x".format(it) }
+
+    /**
+     * A hard link costs no space. Files in a release never change, so sharing them is safe.
+     * Android before 8.0 has no java.nio.file, so it copies instead.
+     */
+    private fun link(source: File, target: File) {
+        val linked = try {
+            java.nio.file.Files.createLink(target.toPath(), source.toPath())
+            true
+        } catch (error: Exception) {
+            false
+        } catch (error: LinkageError) {
+            false
+        }
+        if (linked) return
+        try {
+            source.copyTo(target, overwrite = true)
+        } catch (error: IOException) {
+            throw RovqException(RovqErrorCode.STORAGE_FAILED, "Could not place a file", error)
+        }
+    }
+}

package/android/src/main/java/com/rovq/engine/UpdateService.kt

@@ -0,0 +1,175 @@
+package com.rovq.engine
+
+import java.io.IOException
+import java.net.HttpURLConnection
+import java.net.URL
+import org.json.JSONArray
+import org.json.JSONException
+import org.json.JSONObject
+
+private const val CONNECT_TIMEOUT_MS = 15_000
+private const val READ_TIMEOUT_MS = 30_000
+
+/** What the device tells the server when asking for updates. */
+data class CheckRequest(
+    val deploymentKey: String,
+    val deviceId: String,
+    val runtimeVersion: String,
+    val binaryVersion: String,
+    val currentReleaseId: String?,
+    val highestSequence: Long,
+)
+
+/** The server's answer. It is advice only, because [OfferedUpdate] is verified before use. */
+sealed interface CheckResponse {
+    data object None : CheckResponse
+    data object Rollback : CheckResponse
+    data class Update(val offer: OfferedUpdate) : CheckResponse
+}
+
+/** A key's signed statement that it must no longer be trusted. The engine verifies it. */
+data class KeyRevocation(val keyId: String, val statement: String, val signature: String)
+
+data class CheckAnswer(
+    val response: CheckResponse,
+    val revocations: List<KeyRevocation> = emptyList(),
+)
+
+/** The server API the engine needs, kept separate so tests can replace it. */
+interface UpdateService {
+    /** @throws IOException if the server cannot be reached or answers with an error. */
+    fun check(request: CheckRequest): CheckAnswer
+
+    /** @throws IOException if the events could not be delivered. */
+    fun report(deploymentKey: String, deviceId: String, events: List<QueuedEvent>)
+
+    /**
+     * Download links for files of a release made of files, by hash. Each file is checked against
+     * the signed manifest, so the links are trusted for nothing.
+     *
+     * @throws IOException if the server cannot be reached or answers with an error.
+     */
+    fun fileLinks(deploymentKey: String, deviceId: String, releaseId: String, hashes: List<String>): Map<String, String>
+}
+
+class HttpUpdateService(
+    private val apiUrl: String,
+    private val allowInsecureUrls: Boolean = false,
+) : UpdateService {
+
+    override fun check(request: CheckRequest): CheckAnswer {
+        val body = JSONObject()
+            .put("deploymentKey", request.deploymentKey)
+            .put("deviceId", request.deviceId)
+            .put("platform", "ANDROID")
+            .put("runtimeVersion", request.runtimeVersion)
+            .put("binaryVersion", request.binaryVersion)
+            .put("highestSequence", request.highestSequence)
+            // Both a ZIP package and a list of files. See docs/file-packages.md.
+            .put("packageFormats", JSONArray().put(1).put(2))
+        request.currentReleaseId?.let { body.put("currentReleaseId", it) }
+
+        return try {
+            val response = post("/device/updates/check", body)
+            val action = when (val action = response.getString("action")) {
+                "NONE" -> CheckResponse.None
+                "ROLLBACK" -> CheckResponse.Rollback
+                "UPDATE" -> {
+                    val update = response.getJSONObject("update")
+                    CheckResponse.Update(
+                        OfferedUpdate(
+                            manifest = update.getString("manifest"),
+                            signature = update.getString("signature"),
+                            keyId = update.getString("keyId"),
+                            // A release made of files has no single download URL.
+                            downloadUrl = update.optString("downloadUrl").ifEmpty { null },
+                        ),
+                    )
+                }
+                else -> throw IOException("Unknown action $action")
+            }
+            CheckAnswer(action, readRevocations(response))
+        } catch (error: JSONException) {
+            throw IOException("The server sent an unreadable response", error)
+        }
+    }
+
+    private fun readRevocations(response: JSONObject): List<KeyRevocation> {
+        val list = response.optJSONArray("revokedKeys") ?: return emptyList()
+        return (0 until list.length()).map { index ->
+            val item = list.getJSONObject(index)
+            KeyRevocation(item.getString("keyId"), item.getString("statement"), item.getString("signature"))
+        }
+    }
+
+    override fun report(deploymentKey: String, deviceId: String, events: List<QueuedEvent>) {
+        val list = JSONArray()
+        events.forEach { event ->
+            val json = JSONObject()
+                .put("clientEventId", event.clientEventId)
+                .put("type", event.type)
+                .put("occurredAt", event.occurredAt)
+            event.releaseId?.let { json.put("releaseId", it) }
+            event.errorCode?.let { json.put("errorCode", it) }
+            list.put(json)
+        }
+        post(
+            "/device/events",
+            JSONObject()
+                .put("deploymentKey", deploymentKey)
+                .put("deviceId", deviceId)
+                .put("events", list),
+        )
+    }
+
+    override fun fileLinks(
+        deploymentKey: String,
+        deviceId: String,
+        releaseId: String,
+        hashes: List<String>,
+    ): Map<String, String> {
+        val response = post(
+            "/device/updates/files",
+            JSONObject()
+                .put("deploymentKey", deploymentKey)
+                .put("deviceId", deviceId)
+                .put("releaseId", releaseId)
+                .put("hashes", JSONArray(hashes)),
+        )
+        return try {
+            val files = response.getJSONArray("files")
+            (0 until files.length()).associate { index ->
+                val file = files.getJSONObject(index)
+                file.getString("hash") to file.getString("url")
+            }
+        } catch (error: JSONException) {
+            throw IOException("The server sent an unreadable response", error)
+        }
+    }
+
+    private fun post(path: String, body: JSONObject): JSONObject {
+        val url = URL(apiUrl.trimEnd('/') + path)
+        if (url.protocol != "https" && !allowInsecureUrls) {
+            throw IOException("The API URL must use HTTPS")
+        }
+        val connection = url.openConnection() as HttpURLConnection
+        try {
+            connection.connectTimeout = CONNECT_TIMEOUT_MS
+            connection.readTimeout = READ_TIMEOUT_MS
+            connection.requestMethod = "POST"
+            connection.doOutput = true
+            connection.setRequestProperty("content-type", "application/json")
+            connection.outputStream.use { it.write(body.toString().toByteArray(Charsets.UTF_8)) }
+            if (connection.responseCode != HttpURLConnection.HTTP_OK) {
+                throw IOException("The server answered ${connection.responseCode}")
+            }
+            return try {
+                JSONObject(connection.inputStream.bufferedReader().use { it.readText() })
+            } catch (error: JSONException) {
+                throw IOException("The server sent an unreadable response", error)
+            }
+        } finally {
+            connection.disconnect()
+        }
+    }
+}