@umutcansu/react-native-pinvault 0.0.0-stage → 2.3.2

package/android/src/main/java/io/github/umutcansu/pinvault/reactnative/PinVaultNetworking.kt

@@ -0,0 +1,296 @@
+package io.github.umutcansu.pinvault.reactnative
+
+import android.content.ContentProvider
+import android.content.ContentValues
+import android.content.Context
+import android.database.Cursor
+import android.net.Uri
+import android.util.Log
+import com.facebook.react.modules.network.CustomClientBuilder
+import com.facebook.react.modules.network.NetworkingModule
+import com.facebook.react.modules.network.OkHttpClientFactory
+import com.facebook.react.modules.network.OkHttpClientProvider
+import io.github.umutcansu.pinvault.PinVault
+import okhttp3.Cache
+import okhttp3.CookieJar
+import okhttp3.Interceptor
+import okhttp3.OkHttpClient
+import java.io.File
+import java.io.IOException
+import java.net.InetAddress
+import java.net.Socket
+import java.security.cert.X509Certificate
+import javax.net.ssl.SSLHandshakeException
+import javax.net.ssl.SSLSocketFactory
+import javax.net.ssl.X509TrustManager
+
+/**
+ * Pins React Native's own networking (global `fetch` / `XMLHttpRequest`,
+ * `WebSocket`, and `<Image>` through Fresco) with `PinVault.applyTo(builder)` —
+ * Android only.
+ *
+ * Installed **automatically before the app's code runs**: the plugin's manifest
+ * declares [PinVaultNetworkingInitializer], a `ContentProvider`, and Android
+ * creates content providers before `Application.onCreate` (the AndroidX
+ * Startup pattern, without the dependency). [install] stays as an explicit
+ * alternative for apps that remove the provider.
+ *
+ * Two hooks, both verified against React Native 0.87's sources:
+ *
+ * - `NetworkingModule.setCustomClientBuilder`: RN calls it for **every**
+ *   fetch / XHR request on `client.newBuilder()`. Each request gets the
+ *   pinned socket factory and PinVault's interceptors (pin check of pooled
+ *   connections, `PinVault-Token`, pin-mismatch recovery) of one client that
+ *   `PinVault.applyTo` configured after `start()` — one per start, so pooled
+ *   connections are reused — no disk HTTP cache and no cookie jar (unless
+ *   `android.keepReactNativeHttpCache` / `keepReactNativeCookies`), and no
+ *   `https` → `http` redirects.
+ * - `OkHttpClientProvider.setOkHttpClientFactory`: the clients RN builds once
+ *   and keeps (the networking base client, the WebSocket / dev-support
+ *   singleton, Fresco's image client) get a forwarding socket factory: every
+ *   TLS handshake uses the pinned factory of the current start. No disk
+ *   cache, no `https` → `http` redirects.
+ *
+ * Before `start()` — and after a start that failed — every `https` request
+ * through RN's networking fails (`IOException: PinVault has not started`),
+ * the same fail-closed rule as the library's own `getClient()` / `applyTo`,
+ * which refuse before `init`. Plain `http` is not TLS and is left to the
+ * app's network security config (Metro in debug builds uses it). Hosts
+ * without a pin entry are refused by PinVault's trust manager like
+ * everywhere else.
+ *
+ * Another library that calls `setOkHttpClientFactory` or
+ * `setCustomClientBuilder` after PinVault replaces these hooks: [status]
+ * tells, `start()` and every plugin `fetch` check it and log a warning, and
+ * `requirePinnedReactNativeNetworking: true` makes `start()` fail.
+ */
+object PinVaultNetworking {
+
+    private const val TAG = "PinVault"
+
+    @Volatile private var installed = false
+    @Volatile private var app: Context? = null
+
+    /** The two hooks this object installed; compared by identity in [status]. */
+    private val factory = OkHttpClientFactory {
+        pinning.configureLongLived(OkHttpClientProvider.createClientBuilder()).build()
+    }
+    private val clientBuilder = CustomClientBuilder { builder -> pinning.configurePerRequest(builder) }
+
+    internal val pinning = NetworkPinning(
+        applier = { builder -> PinVault.applyTo(builder) },
+        httpCache = { app?.let { ReactHttpCache.get(it) } },
+    )
+
+    /**
+     * Installs both hooks (once per process). The plugin's content provider
+     * calls it before `Application.onCreate`; call it yourself in
+     * `MainApplication.onCreate`, before `loadReactNative`, only when the app
+     * removed that provider.
+     */
+    @JvmStatic
+    @Synchronized
+    fun install(context: Context) {
+        if (installed) return
+        app = context.applicationContext
+        OkHttpClientProvider.setOkHttpClientFactory(factory)
+        NetworkingModule.setCustomClientBuilder(clientBuilder)
+        installed = true
+    }
+
+    @JvmStatic
+    val isInstalled: Boolean get() = installed
+
+    /** Whether React Native's two networking hooks are still the ones [install] set. */
+    @JvmStatic
+    fun status(): HookStatus = HookStatus.read(installed, factory, clientBuilder)
+
+    private val warned = java.util.concurrent.atomic.AtomicReference<HookStatus?>(null)
+
+    /** Logs a warning when the hooks are not PinVault's, once per distinct state. */
+    internal fun warnIfNotPinned(where: String): HookStatus {
+        val s = status()
+        if (!s.pinned && warned.getAndSet(s) != s) Log.w(TAG, "$where: ${s.describe()}")
+        if (s.pinned) warned.set(null)
+        return s
+    }
+}
+
+/**
+ * What React Native's networking hooks are now. `null` = could not be read
+ * (a React Native version whose internals moved): treated as not pinned.
+ */
+data class HookStatus(
+    val installed: Boolean,
+    /** `OkHttpClientProvider`'s factory is PinVault's. */
+    val factoryIsPinVault: Boolean?,
+    /** `NetworkingModule`'s custom client builder is PinVault's. */
+    val clientBuilderIsPinVault: Boolean?,
+) {
+    val pinned: Boolean get() = installed && factoryIsPinVault == true && clientBuilderIsPinVault == true
+
+    fun describe(): String = when {
+        pinned -> "React Native's networking is pinned by PinVault"
+        !installed -> "React Native's networking hooks are not installed (the plugin's content provider was removed " +
+            "and PinVaultNetworking.install was not called, or android.pinGlobalNetworking is false): " +
+            "RN fetch / XHR / WebSocket / images are NOT pinned"
+        else -> buildList {
+            if (factoryIsPinVault != true) add("OkHttpClientProvider's client factory " + if (factoryIsPinVault == null) "could not be read" else "was replaced by another library")
+            if (clientBuilderIsPinVault != true) add("NetworkingModule's custom client builder " + if (clientBuilderIsPinVault == null) "could not be read" else "was replaced by another library")
+        }.joinToString("; ") + ": React Native's own networking may NOT be pinned"
+    }
+
+    internal companion object {
+        fun read(installed: Boolean, ourFactory: Any, ourBuilder: Any): HookStatus = HookStatus(
+            installed,
+            isOurs(OkHttpClientProvider::class.java, "factory", ourFactory),
+            isOurs(NetworkingModule::class.java, "customClientBuilder", ourBuilder),
+        )
+
+        /**
+         * Whether RN's private static field [name] holds [ours]; null when it
+         * cannot be read. The plugin's consumer R8 rules keep both fields' names.
+         */
+        private fun isOurs(owner: Class<*>, name: String, ours: Any): Boolean? = try {
+            owner.getDeclaredField(name).apply { isAccessible = true }.get(null) === ours
+        } catch (_: ReflectiveOperationException) {
+            null
+        } catch (_: RuntimeException) {
+            null
+        }
+    }
+}
+
+/**
+ * Installs [PinVaultNetworking] when the app process starts, before
+ * `Application.onCreate`. Opt out in the app's manifest:
+ *
+ * ```xml
+ * <provider android:name="io.github.umutcansu.pinvault.reactnative.PinVaultNetworkingInitializer"
+ *     android:authorities="${applicationId}.pinvault-networking" tools:node="remove" />
+ * ```
+ */
+class PinVaultNetworkingInitializer : ContentProvider() {
+    override fun onCreate(): Boolean {
+        context?.let { PinVaultNetworking.install(it) }
+        return true
+    }
+
+    override fun query(uri: Uri, projection: Array<out String>?, selection: String?, selectionArgs: Array<out String>?, sortOrder: String?): Cursor? = null
+    override fun getType(uri: Uri): String? = null
+    override fun insert(uri: Uri, values: ContentValues?): Uri? = null
+    override fun delete(uri: Uri, selection: String?, selectionArgs: Array<out String>?): Int = 0
+    override fun update(uri: Uri, values: ContentValues?, selection: String?, selectionArgs: Array<out String>?): Int = 0
+}
+
+/** RN's own 10 MiB disk cache (`OkHttpClientProvider.createClientBuilder(context)`), only with `keepReactNativeHttpCache`. */
+internal object ReactHttpCache {
+    @Volatile private var cache: Cache? = null
+
+    fun get(context: Context): Cache = cache ?: synchronized(this) {
+        cache ?: Cache(File(context.cacheDir, "http-cache"), 10L * 1024 * 1024).also { cache = it }
+    }
+}
+
+/**
+ * The mechanics of [PinVaultNetworking], with the `applyTo` call injected so
+ * that JVM tests can run it without a device.
+ */
+internal class NetworkPinning(
+    private val applier: (OkHttpClient.Builder) -> Unit,
+    private val httpCache: () -> Cache? = { null },
+) {
+
+    /** A client `PinVault.applyTo` configured after the last `start()`; null = not started. */
+    @Volatile private var template: OkHttpClient? = null
+    @Volatile var options: NetworkingOptions = NetworkingOptions()
+
+    val isActive: Boolean get() = template != null
+
+    /** After `start()`: one pinned template per start (its socket factory keys the connection pool). */
+    @Synchronized
+    fun activate(options: NetworkingOptions = this.options) {
+        this.options = options
+        template = OkHttpClient.Builder().also(applier).build()
+    }
+
+    @Synchronized
+    fun deactivate() {
+        template = null
+    }
+
+    /** NetworkingModule's per-request builder (fetch / XHR). */
+    fun configurePerRequest(builder: OkHttpClient.Builder) {
+        // Never from https into plain http; not even before start (the gate below refuses https anyway).
+        builder.followSslRedirects(false)
+        val o = options
+        builder.cache(if (o.keepHttpCache) httpCache() else null)
+        // RN puts its persistent cookie jar (Android's CookieManager) on its base client;
+        // NO_COOKIES = nothing is sent or stored. RN itself sets NO_COOKIES for withCredentials: false.
+        if (!o.keepCookies) builder.cookieJar(CookieJar.NO_COOKIES)
+        val pinned = template
+        if (pinned == null) {
+            if (httpsGate !in builder.interceptors()) builder.addInterceptor(httpsGate)
+            return
+        }
+        builder.sslSocketFactory(pinned.sslSocketFactory, requireNotNull(pinned.x509TrustManager))
+        builder.hostnameVerifier(pinned.hostnameVerifier)
+        builder.certificatePinner(pinned.certificatePinner)
+        // A builder derived from a client this method already configured would
+        // carry the interceptors twice; RN derives every request from its base client.
+        pinned.interceptors.forEach { if (it !in builder.interceptors()) builder.addInterceptor(it) }
+        pinned.networkInterceptors.forEach { if (it !in builder.networkInterceptors()) builder.addNetworkInterceptor(it) }
+    }
+
+    /** Clients RN builds once and keeps: TLS goes through the pinned factory of the current start. */
+    fun configureLongLived(builder: OkHttpClient.Builder): OkHttpClient.Builder {
+        val forwarding = ForwardingSocketFactory { template?.sslSocketFactory }
+        builder.sslSocketFactory(forwarding, ForwardingTrustManager { template?.x509TrustManager })
+        builder.addInterceptor(httpsGate)
+        builder.cache(null)
+        builder.followSslRedirects(false)
+        return builder
+    }
+
+    /** Refuses `https` while PinVault has not started. */
+    private val httpsGate = Interceptor { chain ->
+        if (chain.request().isHttps && template == null) {
+            throw IOException("PinVault has not started: https requests are refused until start() returns")
+        }
+        chain.proceed(chain.request())
+    }
+}
+
+/** Hands every socket to the pinned factory of the current start; none before `start()`. */
+internal class ForwardingSocketFactory(private val current: () -> SSLSocketFactory?) : SSLSocketFactory() {
+
+    private fun delegate(): SSLSocketFactory =
+        current() ?: throw SSLHandshakeException("PinVault has not started: TLS is refused until start() returns")
+
+    override fun getDefaultCipherSuites(): Array<String> = current()?.defaultCipherSuites ?: emptyArray()
+    override fun getSupportedCipherSuites(): Array<String> = current()?.supportedCipherSuites ?: emptyArray()
+    override fun createSocket(s: Socket?, host: String?, port: Int, autoClose: Boolean): Socket =
+        delegate().createSocket(s, host, port, autoClose)
+    override fun createSocket(host: String?, port: Int): Socket = delegate().createSocket(host, port)
+    override fun createSocket(host: String?, port: Int, localHost: InetAddress?, localPort: Int): Socket =
+        delegate().createSocket(host, port, localHost, localPort)
+    override fun createSocket(host: InetAddress?, port: Int): Socket = delegate().createSocket(host, port)
+    override fun createSocket(address: InetAddress?, port: Int, localAddress: InetAddress?, localPort: Int): Socket =
+        delegate().createSocket(address, port, localAddress, localPort)
+    override fun createSocket(): Socket = delegate().createSocket()
+}
+
+/**
+ * OkHttp uses this trust manager only to clean certificate chains; the
+ * handshake itself is checked inside the pinned socket factory.
+ */
+internal class ForwardingTrustManager(private val current: () -> X509TrustManager?) : X509TrustManager {
+    private fun delegate(): X509TrustManager =
+        current() ?: throw java.security.cert.CertificateException("PinVault has not started")
+
+    override fun checkClientTrusted(chain: Array<out X509Certificate>?, authType: String?) =
+        delegate().checkClientTrusted(chain, authType)
+    override fun checkServerTrusted(chain: Array<out X509Certificate>?, authType: String?) =
+        delegate().checkServerTrusted(chain, authType)
+    override fun getAcceptedIssuers(): Array<X509Certificate> = current()?.acceptedIssuers ?: emptyArray()
+}

package/android/src/main/java/io/github/umutcansu/pinvault/reactnative/PinVaultPackage.kt

@@ -0,0 +1,25 @@
+package io.github.umutcansu.pinvault.reactnative
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+class PinVaultPackage : BaseReactPackage() {
+    override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? =
+        if (name == PinVaultModule.NAME) PinVaultModule(reactContext) else null
+
+    override fun getReactModuleInfoProvider() = ReactModuleInfoProvider {
+        mapOf(
+            PinVaultModule.NAME to ReactModuleInfo(
+                name = PinVaultModule.NAME,
+                className = PinVaultModule.NAME,
+                canOverrideExistingModule = false,
+                needsEagerInit = false,
+                isCxxModule = false,
+                isTurboModule = true,
+            )
+        )
+    }
+}

package/android/src/main/java/io/github/umutcansu/pinvault/reactnative/PinnedFetch.kt

@@ -0,0 +1,131 @@
+package io.github.umutcansu.pinvault.reactnative
+
+import io.github.umutcansu.pinvault.model.HttpConnectionSettings
+import okhttp3.Headers
+import okhttp3.HttpUrl
+import okhttp3.HttpUrl.Companion.toHttpUrlOrNull
+import okhttp3.MediaType.Companion.toMediaTypeOrNull
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.RequestBody.Companion.toRequestBody
+import okio.Buffer
+import okio.ByteString.Companion.decodeBase64
+import java.io.IOException
+import java.util.concurrent.TimeUnit
+
+/** A `fetch(url, init)` from JS, checked. */
+internal class FetchRequest(
+    val url: HttpUrl,
+    val method: String,
+    val headers: Headers,
+    val body: ByteArray?,
+    val responseEncoding: String,
+    val timeoutMs: Long?,
+    val maxResponseBytes: Long,
+    val settings: HttpConnectionSettings?,
+)
+
+/** The response was larger than the request allowed. */
+internal class ResponseTooLargeException(limit: Long) : IOException("Response larger than $limit bytes")
+
+/**
+ * The plugin's own `fetch`: parsed strictly, sent through the pinned client
+ * the library hands out (`PinVault.getClient()` or `getClient(settings)`),
+ * HTTPS only, bounded in both directions. A redirect from `https` into plain
+ * `http` is not followed (the 3xx comes back), as on iOS.
+ */
+internal object PinnedFetch {
+
+    const val MAX_REQUEST_BYTES = 10L * 1024 * 1024
+    const val DEFAULT_MAX_RESPONSE_BYTES = 10L * 1024 * 1024
+    const val MAX_RESPONSE_BYTES = 50L * 1024 * 1024
+    private val METHODS = setOf("GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS")
+    private val TOKEN = Regex("[!#$%&'*+.^_`|~0-9A-Za-z-]{1,256}")
+
+    fun parse(json: String): FetchRequest {
+        // Base64 inflates by 4/3; leave room for the other fields.
+        val f = StrictJson.parseObject(json, "request", maxChars = (MAX_REQUEST_BYTES * 4 / 3 + 64 * 1024).toInt())
+        val urlText = f.requireString("url", 8192)
+        val url = urlText.toHttpUrlOrNull() ?: throw BridgeInputException("request.url: not a valid URL")
+        if (!url.isHttps) throw BridgeInputException("request.url: only https:// URLs go through the pinned client")
+        val method = (f.string("method", 16) ?: "GET").uppercase()
+        if (method !in METHODS) throw BridgeInputException("request.method: '$method' is not supported")
+        val headers = Headers.Builder()
+        f.stringMap("headers", 128, 256, 8192)?.forEach { (name, value) ->
+            if (!TOKEN.matches(name)) throw BridgeInputException("request.headers: '${name.take(40)}' is not a header name")
+            if (value.any { it == '\r' || it == '\n' || it.code == 0 }) {
+                throw BridgeInputException("request.headers.$name: line breaks are not allowed")
+            }
+            headers.add(name, value)
+        }
+        val bodyText = f.text("body", (MAX_REQUEST_BYTES * 4 / 3 + 4).toInt())
+        val bodyEncoding = ResultMapper.checkEncoding(f.string("bodyEncoding", 16) ?: ResultMapper.UTF8)
+        val body = bodyText?.let {
+            if (bodyEncoding == ResultMapper.BASE64) {
+                it.decodeBase64()?.toByteArray() ?: throw BridgeInputException("request.body: not valid Base64")
+            } else {
+                it.toByteArray(Charsets.UTF_8)
+            }
+        }
+        if (body != null && body.size > MAX_REQUEST_BYTES) throw BridgeInputException("request.body: larger than $MAX_REQUEST_BYTES bytes")
+        if (body != null && (method == "GET" || method == "HEAD")) throw BridgeInputException("request.body: $method has no body")
+        val responseEncoding = ResultMapper.checkEncoding(f.string("responseEncoding", 16) ?: ResultMapper.UTF8)
+        val timeoutMs = f.long("timeoutMs", 1, 10 * 60 * 1000L)
+        val maxResponse = f.long("maxResponseBytes", 1, MAX_RESPONSE_BYTES) ?: DEFAULT_MAX_RESPONSE_BYTES
+        val settings = f.obj("settings")?.let { s ->
+            val d = HttpConnectionSettings()
+            val parsed = HttpConnectionSettings(
+                connectTimeout = s.long("connectTimeout", 0, 600) ?: d.connectTimeout,
+                readTimeout = s.long("readTimeout", 0, 600) ?: d.readTimeout,
+                writeTimeout = s.long("writeTimeout", 0, 600) ?: d.writeTimeout,
+                callTimeout = s.long("callTimeout", 0, 600) ?: d.callTimeout,
+            )
+            s.finish()
+            parsed
+        }
+        f.finish()
+        return FetchRequest(url, method, headers.build(), body, responseEncoding, timeoutMs, maxResponse, settings)
+    }
+
+    /** Runs [request] on [client] (a pinned client from the library); blocking. */
+    fun execute(client: OkHttpClient, request: FetchRequest): Map<String, Any?> {
+        // newBuilder shares the pool, the pinned socket factory and the
+        // library's interceptors; it only stops https → http redirects.
+        val callClient = client.newBuilder().followSslRedirects(false).build()
+        val contentType = request.headers["Content-Type"]?.toMediaTypeOrNull()
+        val body = when {
+            request.body != null -> request.body.toRequestBody(contentType)
+            request.method in setOf("POST", "PUT", "PATCH") -> ByteArray(0).toRequestBody(contentType)
+            else -> null
+        }
+        val okRequest = Request.Builder().url(request.url).headers(request.headers).method(request.method, body).build()
+        val call = callClient.newCall(okRequest)
+        request.timeoutMs?.let { call.timeout().timeout(it, TimeUnit.MILLISECONDS) }
+        call.execute().use { response ->
+            val responseBody = response.body
+            val declared = responseBody?.contentLength() ?: -1L
+            if (declared > request.maxResponseBytes) throw ResponseTooLargeException(request.maxResponseBytes)
+            val buffer = Buffer()
+            if (responseBody != null) {
+                val source = responseBody.source()
+                while (true) {
+                    val read = source.read(buffer, 64 * 1024L)
+                    if (read == -1L) break
+                    if (buffer.size > request.maxResponseBytes) throw ResponseTooLargeException(request.maxResponseBytes)
+                }
+            }
+            val bytes = buffer.readByteArray()
+            val headers = LinkedHashMap<String, String>()
+            response.headers.names().forEach { name ->
+                headers[name.lowercase()] = response.headers.values(name).joinToString(", ")
+            }
+            return mapOf(
+                "status" to response.code,
+                "url" to response.request.url.toString(),
+                "headers" to headers,
+                "body" to ResultMapper.encode(bytes, request.responseEncoding),
+                "bodyEncoding" to request.responseEncoding,
+            )
+        }
+    }
+}

package/android/src/main/java/io/github/umutcansu/pinvault/reactnative/ResultMapper.kt

@@ -0,0 +1,188 @@
+package io.github.umutcansu.pinvault.reactnative
+
+import io.github.umutcansu.pinvault.api.PinVaultConnectionEvent
+import io.github.umutcansu.pinvault.model.AttestationStatus
+import io.github.umutcansu.pinvault.model.AttestationTokenResult
+import io.github.umutcansu.pinvault.model.ClientCertEnrollmentResult
+import io.github.umutcansu.pinvault.model.InitResult
+import io.github.umutcansu.pinvault.model.SigningStatus
+import io.github.umutcansu.pinvault.model.UpdateResult
+import io.github.umutcansu.pinvault.model.VaultFileResult
+import io.github.umutcansu.pinvault.model.VaultFileUnlockResult
+import okio.ByteString.Companion.toByteString
+
+/**
+ * Native results → plain maps for JS. `type` is the sealed subclass in
+ * lowerCamel (`Ready` → `ready`), every other key is the Kotlin property name.
+ * Every free-text field goes through [VaultTokenStore.redact]; vault file
+ * content appears only in `unlocked` (after the native prompt) and in
+ * `loadFile`, never in a download result or an event.
+ */
+internal class ResultMapper(private val tokens: VaultTokenStore) {
+
+    private fun text(s: String?): String? = tokens.redact(s)
+
+    fun exception(e: Throwable?): Map<String, Any?>? = e?.let {
+        mapOf("name" to it.javaClass.simpleName.ifEmpty { "Exception" }, "message" to text(it.message))
+    }
+
+    fun init(r: InitResult): Map<String, Any?> = when (r) {
+        is InitResult.Ready -> mapOf("type" to "ready", "version" to r.version)
+        is InitResult.Failed -> mapOf("type" to "failed", "reason" to text(r.reason), "exception" to exception(r.exception))
+    }
+
+    fun update(r: UpdateResult): Map<String, Any?> = when (r) {
+        is UpdateResult.Updated -> mapOf("type" to "updated", "newVersion" to r.newVersion)
+        UpdateResult.AlreadyCurrent -> mapOf("type" to "alreadyCurrent")
+        is UpdateResult.Failed -> mapOf("type" to "failed", "reason" to text(r.reason), "exception" to exception(r.exception))
+    }
+
+    fun enrollment(r: ClientCertEnrollmentResult): Map<String, Any?> = when (r) {
+        is ClientCertEnrollmentResult.Enrolled -> mapOf(
+            "type" to "enrolled",
+            "alreadyEnrolled" to r.alreadyEnrolled,
+            "keySecurityLevel" to r.keySecurityLevel?.name,
+        )
+        is ClientCertEnrollmentResult.Refused -> mapOf(
+            "type" to "refused",
+            "reason" to r.reason.name,
+            "httpStatus" to r.httpStatus,
+            "serverError" to text(r.serverError),
+            "message" to text(r.message),
+        )
+        is ClientCertEnrollmentResult.Pending -> mapOf(
+            "type" to "pending",
+            "requestId" to r.requestId,
+            "clientId" to r.clientId,
+            "message" to text(r.message),
+            "retryAfterSeconds" to r.retryAfterSeconds,
+            "verificationCode" to r.verificationCode,
+        )
+        is ClientCertEnrollmentResult.Failed -> mapOf(
+            "type" to "failed",
+            "message" to text(r.message),
+            "cause" to exception(r.cause),
+        )
+    }
+
+    fun vaultFile(r: VaultFileResult): Map<String, Any?> = when (r) {
+        // No bytes: the content is read with loadFile / unlockFile, on purpose.
+        is VaultFileResult.Updated -> mapOf("type" to "updated", "key" to r.key, "version" to r.version)
+        is VaultFileResult.AlreadyCurrent -> mapOf("type" to "alreadyCurrent", "key" to r.key, "version" to r.version)
+        is VaultFileResult.Failed -> mapOf(
+            "type" to "failed",
+            "key" to r.key,
+            "reason" to text(r.reason),
+            "code" to r.code,
+            "exception" to exception(r.exception),
+        )
+    }
+
+    fun unlock(r: VaultFileUnlockResult, encoding: String): Map<String, Any?> = when (r) {
+        is VaultFileUnlockResult.Unlocked -> mapOf(
+            "type" to "unlocked",
+            "key" to r.key,
+            "version" to r.version,
+            "content" to encode(r.bytes, encoding),
+            "encoding" to encoding,
+        )
+        is VaultFileUnlockResult.NotFound -> mapOf("type" to "notFound", "key" to r.key)
+        is VaultFileUnlockResult.Cancelled -> mapOf("type" to "cancelled", "key" to r.key)
+        is VaultFileUnlockResult.Invalidated -> mapOf("type" to "invalidated", "key" to r.key)
+        is VaultFileUnlockResult.Stale -> mapOf("type" to "stale", "key" to r.key)
+        is VaultFileUnlockResult.Failed -> mapOf(
+            "type" to "failed",
+            "key" to r.key,
+            "reason" to text(r.reason),
+            "exception" to exception(r.exception),
+        )
+    }
+
+    fun attestation(s: AttestationStatus): Map<String, Any?> = mapOf(
+        "configApiId" to s.configApiId,
+        "result" to s.result.name,
+        "arc" to s.arc,
+        "rejectionReasons" to s.rejectionReasons,
+        "warnings" to s.warnings,
+        "tokenExpiresAt" to s.tokenExpiresAt,
+        "lastAttestedAt" to s.lastAttestedAt,
+        "nextAttestAt" to s.nextAttestAt,
+        "clockSkewMs" to s.clockSkewMs,
+        "lastError" to text(s.lastError),
+        "policyVersion" to s.policyVersion,
+    )
+
+    fun attestationToken(r: AttestationTokenResult): Map<String, Any?> = when (r) {
+        is AttestationTokenResult.Token -> mapOf("type" to "token", "value" to r.value, "expiresAt" to r.expiresAt)
+        is AttestationTokenResult.Rejected -> mapOf("type" to "rejected", "status" to attestation(r.status))
+        is AttestationTokenResult.Failed -> mapOf("type" to "failed", "message" to text(r.message))
+        AttestationTokenResult.Unsupported -> mapOf("type" to "unsupported")
+    }
+
+    fun signing(s: SigningStatus): Map<String, Any?> = mapOf(
+        "configApiId" to s.configApiId,
+        "trustedKeyIds" to s.trustedKeyIds,
+        "requiredSignatures" to s.requiredSignatures,
+        "keySetVersion" to s.keySetVersion,
+        "recoveryKeyIds" to s.recoveryKeyIds,
+        "lastConfigSignedBy" to s.lastConfigSignedBy,
+    )
+
+    /** Connection telemetry. The library puts no token in events; free text is redacted anyway. */
+    fun event(e: PinVaultConnectionEvent): Map<String, Any?> = when (e) {
+        is PinVaultConnectionEvent.Connection -> mapOf(
+            "type" to "connection",
+            "hostname" to e.hostname,
+            "success" to e.success,
+            "pinVersion" to e.pinVersion,
+            "deviceManufacturer" to e.deviceManufacturer,
+            "deviceModel" to e.deviceModel,
+            "actualPin" to e.actualPin,
+            "expectedPins" to e.expectedPins,
+        )
+        is PinVaultConnectionEvent.ConfigUpdate -> mapOf(
+            "type" to "configUpdate",
+            "status" to e.status.name,
+            "newVersion" to e.newVersion,
+            "deviceManufacturer" to e.deviceManufacturer,
+            "deviceModel" to e.deviceModel,
+            "failureReason" to text(e.failureReason),
+        )
+        is PinVaultConnectionEvent.ClientCertRenewal -> mapOf(
+            "type" to "clientCertRenewal",
+            "status" to e.status.name,
+            "notAfterEpochMs" to e.notAfterEpochMs,
+            "via" to e.via?.name,
+            "configApiId" to e.configApiId,
+            "deviceManufacturer" to e.deviceManufacturer,
+            "deviceModel" to e.deviceModel,
+            "failureReason" to text(e.failureReason),
+        )
+        is PinVaultConnectionEvent.Attestation -> mapOf(
+            "type" to "attestation",
+            "configApiId" to e.configApiId,
+            "status" to e.status.name,
+            "arc" to e.arc,
+            "rejectionReasons" to e.rejectionReasons,
+            "warnings" to e.warnings,
+            "tokenExpiresAt" to e.tokenExpiresAt,
+            "deviceManufacturer" to e.deviceManufacturer,
+            "deviceModel" to e.deviceModel,
+            "failureReason" to text(e.failureReason),
+        )
+    }
+
+    companion object {
+        const val UTF8 = "utf8"
+        const val BASE64 = "base64"
+
+        fun checkEncoding(encoding: String): String {
+            if (encoding != UTF8 && encoding != BASE64) throw BridgeInputException("encoding: must be 'utf8' or 'base64'")
+            return encoding
+        }
+
+        fun encode(bytes: ByteArray, encoding: String): String =
+            // Okio, not android.util.Base64: it also runs in JVM unit tests (and java.util.Base64 needs API 26).
+            if (encoding == BASE64) bytes.toByteString().base64() else bytes.toString(Charsets.UTF_8)
+    }
+}