@mentra/crust 3.3.0-dev.944 → 3.4.0-beta.1237

package/android/build.gradle

@@ -100,13 +100,16 @@ dependencies {
   // APK weight). `:navigation` is the core engine; `:tripdata` carries the
   // banner/maneuver formatting used to label turns.
   // Version pinned to 3.25.0 — re-check https://docs.mapbox.com/android/navigation/releases/
+  // The -ndk27 artifacts are Mapbox's 16 KB page-aligned builds. The
+  // unsuffixed 3.25.0 artifacts still ship 4 KB-aligned native libraries,
+  // which Google Play rejects for 64-bit updates after Feb 1, 2027.
   def isChinaBuild = System.getenv("EXPO_PUBLIC_DEPLOYMENT_REGION") == "china"
   if (isChinaBuild) {
-    compileOnly 'com.mapbox.navigationcore:navigation:3.25.0'
-    compileOnly 'com.mapbox.navigationcore:tripdata:3.25.0'
+    compileOnly 'com.mapbox.navigationcore:navigation-ndk27:3.25.0'
+    compileOnly 'com.mapbox.navigationcore:tripdata-ndk27:3.25.0'
   } else {
-    implementation 'com.mapbox.navigationcore:navigation:3.25.0'
-    implementation 'com.mapbox.navigationcore:tripdata:3.25.0'
+    implementation 'com.mapbox.navigationcore:navigation-ndk27:3.25.0'
+    implementation 'com.mapbox.navigationcore:tripdata-ndk27:3.25.0'
   }
 
   // Required for Java 8+ APIs on minSdk < 26 (was needed by Google Nav SDK;
@@ -149,6 +152,15 @@ dependencies {
 dependencies {
   testImplementation 'junit:junit:4.13.2'
   testImplementation 'org.robolectric:robolectric:4.11.1'
+  // Local HTTP server for the miniapp fetch bridge tests; matches okhttp above.
+  testImplementation 'com.squareup.okhttp3:mockwebserver:4.12.0'
+}
+
+// Robolectric loads classes, and so QuickJS's JNI library, in its own sandbox
+// class loader. Plain JUnit QuickJS tests in the same JVM then crash inside
+// JNI, so every test class runs in a fresh JVM.
+tasks.withType(Test).configureEach {
+  forkEvery = 1
 }
 
 // A desktop JVM cannot load the Android QuickJS library, so local unit tests

package/android/src/main/java/com/mentra/crust/CrustModule.kt

@@ -24,6 +24,7 @@ import com.mentra.crust.jsc.InstalledMiniappManifest
 import com.mentra.crust.jsc.JSCPolyfillBridge
 import com.mentra.crust.http.NativeHttpRequests
 import com.mentra.crust.http.nativeHttpFailureCode
+import com.mentra.crust.utils.CanonicalFilePath
 
 class CrustModule : Module() {
   companion object {
@@ -185,6 +186,11 @@ class CrustModule : Module() {
       sendEvent("onChange", mapOf("value" to value))
     }
 
+    // Where a path really is, symlinks resolved; the engine checks miniapp-named paths with it.
+    Function("canonicalFilePath") { path: String ->
+      CanonicalFilePath.of(path)
+    }
+
     AsyncFunction("captureMiniappPreview") Coroutine { viewTag: Int ->
       val activity = appContext.currentActivity ?: error("No activity available for screenshot")
       PixelCopyPreview.capture(activity, viewTag)

package/android/src/main/java/com/mentra/crust/jsc/JSCPolyfillBridge.kt

@@ -2,6 +2,8 @@ package com.mentra.crust.jsc
 
 import android.util.Log
 import java.io.IOException
+import java.nio.ByteBuffer
+import java.nio.charset.CharacterCodingException
 import okhttp3.MediaType.Companion.toMediaTypeOrNull
 import okhttp3.OkHttpClient
 import okhttp3.Request
@@ -12,6 +14,7 @@ import okhttp3.Callback
 import okhttp3.WebSocket
 import okhttp3.WebSocketListener
 import okio.ByteString
+import okio.ByteString.Companion.decodeBase64
 import okio.ByteString.Companion.toByteString
 import org.json.JSONObject
 import org.json.JSONArray
@@ -46,15 +49,23 @@ object JSCPolyfillBridge {
     }
 
     /** Keep host HTTP and miniapp fetch body semantics identical, including empty POSTs. */
-    internal fun buildHttpRequest(method: String, url: String, headers: Map<String, String>, bodyString: String?): Request {
+    internal fun buildHttpRequest(
+        method: String,
+        url: String,
+        headers: Map<String, String>,
+        bodyString: String?,
+        bodyBytes: ByteString? = null,
+    ): Request {
         val builder = Request.Builder().url(url)
         for ((name, value) in headers) builder.header(name, value)
         val contentType = headers.entries
             .firstOrNull { (name, _) -> name.equals("content-type", ignoreCase = true) }
             ?.value
+        val mediaType = (contentType ?: "application/octet-stream").toMediaTypeOrNull()
         val upperMethod = method.uppercase()
         val requestBody = when {
-            bodyString != null -> bodyString.toRequestBody((contentType ?: "application/octet-stream").toMediaTypeOrNull())
+            bodyBytes != null -> bodyBytes.toRequestBody(mediaType)
+            bodyString != null -> bodyString.toRequestBody(mediaType)
             upperMethod == "POST" || upperMethod == "PUT" || upperMethod == "PATCH" -> "".toRequestBody(null)
             else -> null
         }
@@ -62,6 +73,49 @@ object JSCPolyfillBridge {
         return builder.build()
     }
 
+    /**
+     * The `result` of a `fetch.request` response envelope. The body is sent
+     * as the string `body` only when its bytes are exactly that string's
+     * UTF-8 encoding, and as `bodyBase64` otherwise, so binary bodies keep
+     * every byte. The JS polyfill decodes base64 bodies and applies UTF-8 rules.
+     */
+    internal fun fetchResult(response: Response): JSONObject {
+        val headerMap = mutableMapOf<String, String>()
+        for (name in response.headers.names()) {
+            headerMap[name.lowercase()] = response.headers.values(name).joinToString(", ")
+        }
+        val body = try {
+            response.body?.bytes() ?: ByteArray(0)
+        } catch (e: Throwable) {
+            Log.w(TAG, "fetch read body threw: ${e.message}")
+            ByteArray(0)
+        }
+        val text = exactUtf8(body)
+        return JSONObject().apply {
+            put("status", response.code)
+            put("statusText", response.message)
+            put("headers", JSONObject(headerMap as Map<*, *>))
+            if (text != null) {
+                put("body", text)
+            } else {
+                put("bodyBase64", body.toByteString().base64())
+            }
+            put("ok", response.code in 200..299)
+        }
+    }
+
+    /** [bytes] as a String when they are exactly its UTF-8 encoding, else null. */
+    private fun exactUtf8(bytes: ByteArray): String? {
+        // A new decoder reports malformed input, so binary fails at its first invalid byte.
+        val text = try {
+            Charsets.UTF_8.newDecoder().decode(ByteBuffer.wrap(bytes)).toString()
+        } catch (_: CharacterCodingException) {
+            return null
+        }
+        // Re-encoding proves the round trip even if a decoder lets an unpaired surrogate through.
+        return text.takeIf { it.toByteArray(Charsets.UTF_8).contentEquals(bytes) }
+    }
+
     /** Idempotent. Call once on host boot, after the dispatcher is created. */
     fun install(runtime: JSCRuntime) {
         installFetch(runtime)
@@ -84,8 +138,15 @@ object JSCPolyfillBridge {
                 ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "ws.open: missing sid")
             val url = req["url"] as? String
                 ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "ws.open: missing url")
+            if (!MiniappNetworkPolicy.allowsWebSocket(url)) {
+                return@register JSCDispatchOutcome.Error("UNSUPPORTED_SCHEME", MiniappNetworkPolicy.WEB_SOCKET_REFUSAL)
+            }
             val protocols = (req["protocols"] as? List<*>)?.mapNotNull { it as? String } ?: emptyList()
-            val builder = Request.Builder().url(url)
+            val builder = try {
+                Request.Builder().url(url)
+            } catch (e: IllegalArgumentException) {
+                return@register JSCDispatchOutcome.Error("INVALID_ARGS", "ws.open: ${e.message}")
+            }
             if (protocols.isNotEmpty()) {
                 builder.header("Sec-WebSocket-Protocol", protocols.joinToString(", "))
             }
@@ -193,6 +254,9 @@ object JSCPolyfillBridge {
             if (reqId == null) {
                 return@register JSCDispatchOutcome.Error("INVALID_ARGS", "fetch.request requires reqId (use __mentraSendRequest)")
             }
+            if (!MiniappNetworkPolicy.allowsFetch(url)) {
+                return@register JSCDispatchOutcome.Error("UNSUPPORTED_SCHEME", MiniappNetworkPolicy.FETCH_REFUSAL)
+            }
 
             val method = (req["method"] as? String) ?: "GET"
             val headers = (req["headers"] as? Map<*, *>)?.mapNotNull { (k, v) ->
@@ -201,8 +265,16 @@ object JSCPolyfillBridge {
                 ks to vs
             }?.toMap() ?: emptyMap()
             val bodyString = req["body"] as? String
+            val bodyBytes = (req["bodyBase64"] as? String)?.let { encoded ->
+                encoded.decodeBase64()
+                    ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "fetch.request: bodyBase64 is not base64")
+            }
 
-            val request = buildHttpRequest(method, url, headers, bodyString)
+            val request = try {
+                buildHttpRequest(method, url, headers, bodyString, bodyBytes)
+            } catch (e: IllegalArgumentException) {
+                return@register JSCDispatchOutcome.Error("INVALID_ARGS", "fetch.request: ${e.message}")
+            }
 
             httpClient.newCall(request).enqueue(object : Callback {
                 override fun onFailure(call: Call, e: IOException) {
@@ -210,33 +282,14 @@ object JSCPolyfillBridge {
                 }
 
                 override fun onResponse(call: Call, response: Response) {
-                    response.use { r ->
-                        val status = r.code
-                        val statusText = r.message
-                        val headerMap = mutableMapOf<String, String>()
-                        for (name in r.headers.names()) {
-                            headerMap[name.lowercase()] = r.headers.values(name).joinToString(", ")
-                        }
-                        val bodyStr = try {
-                            r.body?.string() ?: ""
-                        } catch (e: Throwable) {
-                            Log.w(TAG, "fetch read body threw: ${e.message}")
-                            ""
-                        }
-                        val envelope = JSONObject().apply {
-                            put("kind", "response")
-                            put("reqId", reqId)
-                            put("ok", true)
-                            put("result", JSONObject().apply {
-                                put("status", status)
-                                put("statusText", statusText)
-                                put("headers", JSONObject(headerMap as Map<*, *>))
-                                put("body", bodyStr)
-                                put("ok", status in 200..299)
-                            })
-                        }
-                        runtime.dispatchToJs(packageName, envelope.toString())
+                    val result = response.use { fetchResult(it) }
+                    val envelope = JSONObject().apply {
+                        put("kind", "response")
+                        put("reqId", reqId)
+                        put("ok", true)
+                        put("result", result)
                     }
+                    runtime.dispatchToJs(packageName, envelope.toString())
                 }
             })
             JSCDispatchOutcome.Async

package/android/src/main/java/com/mentra/crust/jsc/MiniappNetworkPolicy.kt

@@ -0,0 +1,25 @@
+package com.mentra.crust.jsc
+
+/**
+ * Which URLs miniapp code may open through the polyfill's network bridge. Miniapp code is
+ * untrusted, so `fetch` and `WebSocket` reach only the network: never a `file:` URL (the
+ * Mentra App's own files), a `content:` URI or any other local scheme. Mirrors iOS
+ * `MiniappNetworkPolicy.swift` and the polyfill's own check, which miniapp code can skip by
+ * calling the bridge directly.
+ */
+object MiniappNetworkPolicy {
+    /** Leading C0 controls and spaces are skipped, as OkHttp's URL parser does. */
+    private val SCHEME = Regex("^[\\u0000-\\u0020]*([A-Za-z][A-Za-z0-9+.-]*):")
+    private val FETCH_SCHEMES = setOf("http", "https")
+    private val WEB_SOCKET_SCHEMES = setOf("ws", "wss", "http", "https")
+
+    const val FETCH_REFUSAL = "fetch: only http: and https: URLs are allowed"
+    const val WEB_SOCKET_REFUSAL = "ws.open: only ws:, wss:, http: and https: URLs are allowed"
+
+    /** The URL's scheme, lowercased, or null for a URL without one. */
+    fun scheme(url: String): String? = SCHEME.find(url)?.groupValues?.get(1)?.lowercase()
+
+    fun allowsFetch(url: String): Boolean = scheme(url) in FETCH_SCHEMES
+
+    fun allowsWebSocket(url: String): Boolean = scheme(url) in WEB_SOCKET_SCHEMES
+}

package/android/src/main/java/com/mentra/crust/utils/CanonicalFilePath.kt

@@ -0,0 +1,22 @@
+package com.mentra.crust.utils
+
+import java.io.File
+import java.io.IOException
+
+/**
+ * The real location of a path, for checking that a path a miniapp names stays inside the
+ * directory the host allows: absolute, with `.`, `..` and every symlink resolved.
+ */
+object CanonicalFilePath {
+    /** The canonical path of an existing file or directory, or null when there is none. */
+    fun of(path: String): String? {
+        if (!path.startsWith("/") || path.contains('\u0000')) return null
+        return try {
+            File(path).canonicalFile.takeIf { it.exists() }?.path
+        } catch (e: IOException) {
+            null
+        } catch (e: SecurityException) {
+            null
+        }
+    }
+}

package/android/src/test/java/com/mentra/crust/jsc/FetchBridgeTest.kt

@@ -0,0 +1,277 @@
+package com.mentra.crust.jsc
+
+import java.io.File
+import java.util.concurrent.LinkedBlockingQueue
+import java.util.concurrent.TimeUnit
+import kotlin.math.PI
+import kotlin.math.roundToInt
+import kotlin.math.sin
+import okhttp3.MediaType.Companion.toMediaType
+import okhttp3.Protocol
+import okhttp3.Request
+import okhttp3.Response
+import okhttp3.ResponseBody.Companion.toResponseBody
+import okhttp3.mockwebserver.Dispatcher
+import okhttp3.mockwebserver.MockResponse
+import okhttp3.mockwebserver.MockWebServer
+import okhttp3.mockwebserver.RecordedRequest
+import okio.Buffer
+import okio.ByteString.Companion.decodeBase64
+import org.junit.After
+import org.junit.Assert.*
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.RuntimeEnvironment
+import org.robolectric.annotation.Config
+
+/**
+ * Miniapp `fetch` end to end on Android's real stack: the shipped startup.js
+ * polyfill in QuickJS, [JSCRuntime]'s dispatcher and `__deliver` path, this
+ * bridge, and OkHttp against a local server. Each miniapp script reports
+ * through a `test` dispatch, which the runtime forwards to `onOutbound`.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [28], manifest = Config.NONE)
+class FetchBridgeTest {
+    private val packageName = "com.mentra.fetchtest"
+    private val results = LinkedBlockingQueue<Map<*, *>>()
+    private lateinit var server: MockWebServer
+    private lateinit var runtime: JSCRuntime
+    @Volatile private var redirectTarget = "file:///etc/hosts"
+
+    /** A 24 kHz 16-bit sine followed by every byte value: mostly not valid UTF-8. */
+    private val pcm = ByteArray(4800 * 2 + 256).also { out ->
+        for (i in 0 until 4800) {
+            val sample = (sin(2 * PI * 220 * i / 24000) * 20000).roundToInt()
+            out[2 * i] = sample.toByte()
+            out[2 * i + 1] = (sample shr 8).toByte()
+        }
+        for (value in 0 until 256) out[9600 + value] = value.toByte()
+    }
+
+    /** Valid UTF-8 that is still binary data: a BOM, NUL and DEL must all survive. */
+    private val utf8Bytes = byteArrayOf(0xEF.toByte(), 0xBB.toByte(), 0xBF.toByte()) +
+        "{\"a\":\"é😀\"}".toByteArray(Charsets.UTF_8) + byteArrayOf(0x00, 0x7F)
+
+    /** Two MB of valid UTF-8 text: arrayBuffer() re-encodes it inside the 32 MB miniapp heap. */
+    private val largeUtf8Text: ByteArray =
+        "héllo 😀 中文 chunk of reply text ".repeat(52_000).toByteArray(Charsets.UTF_8)
+
+    // crust's build.gradle ships this file as the runtime's startup.js asset.
+    private val polyfill: String by lazy { File("../../jspolyfill/assets/startup.js").readText() }
+
+    @Before fun setUp() {
+        server = MockWebServer().apply {
+            dispatcher = object : Dispatcher() {
+                override fun dispatch(request: RecordedRequest): MockResponse = when (request.path) {
+                    "/reply.pcm" -> response("application/octet-stream").setBody(Buffer().write(pcm))
+                    "/utf8.bin" -> response("application/octet-stream").setBody(Buffer().write(utf8Bytes))
+                    "/large.txt" -> response("text/plain").setBody(Buffer().write(largeUtf8Text))
+                    "/data.json" -> response("application/json").setBody("{\"message\":\"héllo 😀 中文\"}")
+                    "/upload" -> response("text/plain").setBody("ok")
+                    "/to-file" -> MockResponse().setResponseCode(302).setHeader("Location", redirectTarget)
+                    else -> MockResponse().setResponseCode(404)
+                }
+            }
+            start()
+        }
+        runtime = JSCRuntime.shared(RuntimeEnvironment.getApplication())
+        JSCPolyfillBridge.install(runtime)
+        runtime.onOutbound = { message ->
+            if (message.payload["iface"] == "test") {
+                results.add((message.payload["args"] as List<*>).first() as Map<*, *>)
+            }
+        }
+    }
+
+    @After fun tearDown() {
+        runtime.kill(packageName)
+        runtime.onOutbound = null
+        server.shutdown()
+    }
+
+    @Test fun `arrayBuffer returns the exact bytes of a binary response`() {
+        val result = runMiniapp(
+            """
+            const response = await fetch(BASE + "/reply.pcm")
+            const bytes = new Uint8Array(await response.arrayBuffer())
+            return {status: response.status, type: response.headers.get("content-type"), bytes: Array.from(bytes)}
+            """,
+        )
+        assertEquals(200, result["status"])
+        assertEquals("application/octet-stream", result["type"])
+        assertArrayEquals(pcm, bytes(result["bytes"]))
+    }
+
+    @Test fun `arrayBuffer returns the exact bytes of a body that is valid UTF-8`() {
+        val result = runMiniapp(
+            """
+            const response = await fetch(BASE + "/utf8.bin")
+            return {bytes: Array.from(new Uint8Array(await response.arrayBuffer()))}
+            """,
+        )
+        assertArrayEquals(utf8Bytes, bytes(result["bytes"]))
+    }
+
+    @Test fun `arrayBuffer re-encodes a large UTF-8 body within the miniapp heap`() {
+        val result = runMiniapp(
+            """
+            const bytes = new Uint8Array(await (await fetch(BASE + "/large.txt")).arrayBuffer())
+            let sum = 0
+            for (let i = 0; i < bytes.length; i++) sum = (sum * 31 + bytes[i]) >>> 0
+            return {length: bytes.length, sum}
+            """,
+        )
+        var sum = 0L
+        for (byte in largeUtf8Text) sum = (sum * 31 + (byte.toInt() and 0xFF)) and 0xFFFFFFFFL
+        assertEquals(largeUtf8Text.size, (result["length"] as Number).toInt())
+        assertEquals(sum, (result["sum"] as Number).toLong())
+    }
+
+    @Test fun `responses are sent as text only when that text re-encodes to the same bytes`() {
+        val text = JSCPolyfillBridge.fetchResult(responseWith(utf8Bytes))
+        assertEquals(String(utf8Bytes, Charsets.UTF_8), text.getString("body"))
+        assertFalse(text.has("bodyBase64"))
+
+        val empty = JSCPolyfillBridge.fetchResult(responseWith(ByteArray(0)))
+        assertEquals("", empty.getString("body"))
+
+        // Truncated, overlong, surrogate and out-of-range sequences, then raw PCM.
+        for (binary in listOf(byteArrayOf(0x41, 0xE2.toByte(), 0x82.toByte()), byteArrayOf(0xC0.toByte(), 0x80.toByte()),
+            byteArrayOf(0xED.toByte(), 0xA0.toByte(), 0x80.toByte()), byteArrayOf(0xF4.toByte(), 0x90.toByte(), 0x80.toByte(), 0x80.toByte()), pcm)) {
+            val result = JSCPolyfillBridge.fetchResult(responseWith(binary))
+            assertFalse(result.has("body"))
+            assertArrayEquals(binary, result.getString("bodyBase64").decodeBase64()!!.toByteArray())
+        }
+    }
+
+    @Test fun `text and json decode a UTF-8 response`() {
+        val result = runMiniapp(
+            """
+            const text = await (await fetch(BASE + "/data.json")).text()
+            const json = await (await fetch(BASE + "/data.json")).json()
+            return {text, message: json.message}
+            """,
+        )
+        assertEquals("{\"message\":\"héllo 😀 中文\"}", result["text"])
+        assertEquals("héllo 😀 中文", result["message"])
+    }
+
+    @Test fun `binary request bodies reach the server byte for byte`() {
+        val result = runMiniapp(
+            """
+            const backing = Uint8Array.from({length: 600}, (_, i) => (i * 37 + 11) & 255)
+            const response = await fetch(BASE + "/upload", {
+              method: "POST",
+              headers: {"Content-Type": "audio/L16; rate=24000"},
+              body: backing.subarray(44),
+            })
+            return {status: response.status, text: await response.text()}
+            """,
+        )
+        assertEquals(200, result["status"])
+        assertEquals("ok", result["text"])
+        val upload = server.takeRequest()
+        val expected = ByteArray(600) { ((it * 37 + 11) and 255).toByte() }.copyOfRange(44, 600)
+        assertArrayEquals(expected, upload.body.readByteArray())
+        assertEquals("audio/L16; rate=24000", upload.getHeader("Content-Type"))
+    }
+
+    @Test fun `string request bodies keep their UTF-8 text and content type`() {
+        runMiniapp(
+            """
+            await fetch(BASE + "/upload", {method: "POST", headers: {"Content-Type": "application/json"}, body: '{"t":"é😀"}'})
+            return {}
+            """,
+        )
+        val upload = server.takeRequest()
+        assertEquals("{\"t\":\"é😀\"}", upload.body.readUtf8())
+        assertEquals("application/json; charset=utf-8", upload.getHeader("Content-Type"))
+    }
+
+    /**
+     * Miniapp code is untrusted and can call the bridge without the polyfill's own check, so
+     * native must refuse a local URL itself. A file: URL would read the Mentra App's files.
+     */
+    @Test fun `native fetch and WebSocket refuse local URLs even when the polyfill is skipped`() {
+        val secret = File.createTempFile("mentra-credentials", ".txt").apply {
+            writeText("refresh-token-that-must-not-leak")
+            deleteOnExit()
+        }
+        val urls = listOf(secret.toURI().toString(), "FILE://${secret.absolutePath}", "content://com.mentra.mentra.fileprovider/x", "data:text/plain,hi")
+        val result = runMiniapp(
+            """
+            const outcomes = []
+            for (const url of ${org.json.JSONArray(urls)}) {
+              outcomes.push(await __mentraSendRequest("fetch", "request", [{url, method: "GET", headers: {}}]).then(
+                (r) => ({read: String(r && (r.body || r.bodyBase64))}),
+                (e) => ({error: String(e && (e.message || e.code))}),
+              ))
+              let opened = false
+              try {
+                __dispatch("ws", "open", JSON.stringify([{sid: "s-" + outcomes.length, url, protocols: []}]))
+                opened = true
+              } catch (e) {
+                outcomes.push({error: String(e && e.message)})
+              }
+              if (opened) outcomes.push({read: "ws opened"})
+            }
+            return {outcomes}
+            """,
+        )
+        val outcomes = result["outcomes"] as List<*>
+        assertEquals(urls.size * 2, outcomes.size)
+        for (outcome in outcomes) {
+            val map = outcome as Map<*, *>
+            assertNull("a local URL was read: $map", map["read"])
+            assertTrue("unexpected refusal: $map", (map["error"] as String).contains("URLs are allowed"))
+        }
+    }
+
+    /** OkHttp follows a redirect only to another http(s) URL, so a 302 to a file: URL reads nothing. */
+    @Test fun `a redirect to a file URL is not followed`() {
+        val secret = File.createTempFile("mentra-credentials", ".txt").apply {
+            writeText("refresh-token-that-must-not-leak")
+            deleteOnExit()
+        }
+        redirectTarget = secret.toURI().toString()
+        val result = runMiniapp(
+            """
+            const response = await fetch(BASE + "/to-file")
+            return {status: response.status, text: await response.text()}
+            """,
+        )
+        assertEquals(302, result["status"])
+        assertFalse((result["text"] as String).contains("refresh-token"))
+    }
+
+    private fun runMiniapp(body: String): Map<*, *> {
+        val script =
+            """
+            const BASE = "${server.url("/").toString().removeSuffix("/")}"
+            const report = (value) => __mentraSendOneShot("test", "result", [value])
+            ;(async () => {
+              $body
+            })().then(report, (error) => report({error: String(error && (error.message || error))}))
+            """.trimIndent()
+        assertTrue("spawn failed", runtime.spawn(packageName, polyfill, script))
+        val result = results.poll(15, TimeUnit.SECONDS) ?: throw AssertionError("miniapp did not report a result")
+        assertNull("miniapp script threw", result["error"])
+        return result
+    }
+
+    private fun bytes(value: Any?): ByteArray =
+        (value as List<*>).map { (it as Number).toInt().toByte() }.toByteArray()
+
+    private fun response(contentType: String) = MockResponse().setHeader("Content-Type", contentType)
+
+    private fun responseWith(body: ByteArray): Response = Response.Builder()
+        .request(Request.Builder().url("https://example.com/body").build())
+        .protocol(Protocol.HTTP_1_1)
+        .code(200)
+        .message("OK")
+        .body(body.toResponseBody("application/octet-stream".toMediaType()))
+        .build()
+}

package/android/src/test/java/com/mentra/crust/jsc/MiniappNetworkPolicyTest.kt

@@ -0,0 +1,45 @@
+package com.mentra.crust.jsc
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class MiniappNetworkPolicyTest {
+    @Test fun `fetch reaches only http and https`() {
+        for (url in listOf("http://example.com", "https://example.com/a?b", "HTTPS://EXAMPLE.COM", " https://example.com")) {
+            assertTrue(url, MiniappNetworkPolicy.allowsFetch(url))
+        }
+        for (url in listOf(
+            "file:///data/data/com.mentra.mentra/files/mmkv/mmkv.default",
+            "FILE:///etc/hosts",
+            "\tfile:///etc/hosts",
+            "content://com.mentra.mentra.fileprovider/cache/x",
+            "data:text/plain,hi",
+            "jar:file:///x!/y",
+            "ws://example.com",
+            "/data/data/com.mentra.mentra/files",
+            "relative/path",
+            "",
+        )) {
+            assertFalse(url, MiniappNetworkPolicy.allowsFetch(url))
+        }
+    }
+
+    @Test fun `WebSockets reach only ws, wss, http and https`() {
+        for (url in listOf("ws://10.0.0.2:9000", "WSS://example.com/s", "http://example.com", "https://example.com")) {
+            assertTrue(url, MiniappNetworkPolicy.allowsWebSocket(url))
+        }
+        for (url in listOf("file:///etc/hosts", "content://x/y", "data:,x", "/socket")) {
+            assertFalse(url, MiniappNetworkPolicy.allowsWebSocket(url))
+        }
+    }
+
+    @Test fun `scheme is lowercased and absent for a relative URL`() {
+        assertEquals("file", MiniappNetworkPolicy.scheme("FiLe:///x"))
+        assertEquals("https", MiniappNetworkPolicy.scheme("\u0000 https://x"))
+        assertNull(MiniappNetworkPolicy.scheme("/x"))
+        assertNull(MiniappNetworkPolicy.scheme("1http://x"))
+    }
+}

package/android/src/test/java/com/mentra/crust/utils/CanonicalFilePathTest.kt

@@ -0,0 +1,39 @@
+package com.mentra.crust.utils
+
+import java.io.File
+import java.nio.file.Files
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Before
+import org.junit.Test
+
+class CanonicalFilePathTest {
+    private lateinit var root: File
+
+    @Before fun setUp() {
+        root = Files.createTempDirectory("canonical-path-test").toFile().canonicalFile
+    }
+
+    @After fun tearDown() {
+        root.deleteRecursively()
+    }
+
+    @Test fun `resolves dot segments and symlinks to the real location`() {
+        val sandbox = File(root, "sandbox").apply { mkdirs() }
+        val outside = File(root, "outside.txt").apply { writeText("secret") }
+        val link = File(sandbox, "link.txt")
+        Files.createSymbolicLink(link.toPath(), outside.toPath())
+
+        assertEquals(outside.path, CanonicalFilePath.of(link.path))
+        assertEquals(outside.path, CanonicalFilePath.of("${sandbox.path}/../outside.txt"))
+        assertEquals(sandbox.path, CanonicalFilePath.of("${sandbox.path}/./"))
+    }
+
+    @Test fun `is null for a missing, relative or malformed path`() {
+        assertNull(CanonicalFilePath.of("${root.path}/missing.txt"))
+        assertNull(CanonicalFilePath.of("relative/path"))
+        assertNull(CanonicalFilePath.of("${root.path}/a\u0000b"))
+        assertNull(CanonicalFilePath.of(""))
+    }
+}

package/build/CrustModule.d.ts

@@ -9,6 +9,12 @@ declare class CrustModule extends NativeModule<CrustModuleEvents> {
     getPermissionStatus(requestId: string): Promise<AppPermissionReceipt>;
     PI: number;
     hello(): string;
+    /**
+     * The canonical path of an existing file or directory: absolute, with `.`,
+     * `..` and every symlink resolved. Null when nothing is there. The engine
+     * checks that a path a miniapp names stays inside the directory it may use.
+     */
+    canonicalFilePath(path: string): string | null;
     setValueAsync(value: string): Promise<void>;
     /** Android: copy the displayed view's window pixels to a temporary JPEG URI. */
     captureMiniappPreview(viewTag: number): Promise<string>;