pakstr 0.30.0 → 1.0.0

package/README.md

@@ -19,7 +19,7 @@ The CLI API and configuration format may change before 1.0.0.
 
 ## Requirements
 
-*   **Node.js** 22+
+*   **Node.js** 22.12+
 *   **Docker Desktop**
 
 *Note: No Android SDK, Gradle, Java, or Android keystore setup is required locally.*
@@ -49,7 +49,7 @@ build:
 #   apiBase: https://api.example.com  # Optional packaged /api/* proxy target.
 ```
 
-`runtime.apiBase` must be an absolute HTTPS URL. It is the immutable packaged/default proxy target and public APK metadata, not a secret. The effective target precedence is persistent runtime override, then packaged default, then disabled. A web app may call `window.PakstrBridge.setApiBaseUrl(url)` to validate and synchronously persist an HTTPS override, and `window.PakstrBridge.getApiBaseUrl()` to read the effective URL. Developer Tools uses the same setting. Reset removes the override and restores the packaged default; without a packaged default it disables `/api/*`. Changes affect the next proxy request without an app restart, LocalServer restart, or WebView reload.
+`runtime.apiBase` must be an absolute HTTPS URL. It is the immutable packaged/default proxy target and public APK metadata, not a secret. The effective target precedence is persistent runtime override, then packaged default, then disabled. On Android, a web app may call `await window.pakstr.setApiBaseUrl(url)` to validate and persist an HTTPS override (it resolves `true` on success) and `await window.pakstr.getApiBaseUrl()` to read the effective URL; `window.pakstr` exists only in the app's top-level page. Developer Tools uses the same setting. Reset removes the override and restores the packaged default; without a packaged default it disables `/api/*`. Changes affect the next proxy request without an app restart, LocalServer restart, or WebView reload.
 
 ### 3. Build, sign, and publish
 ```bash
@@ -67,6 +67,16 @@ npx pakstr run
 *   `npx pakstr delete --publisher` — Inventory every event authored by the configured publish nsec; add `--execute` for the publisher-wide NIP-09 deletion request.
 *   `npx pakstr run` — Execute the full pipeline at once (**build** + **sign** + **publish**).
 
+### Desktop (macOS arm64, Windows x64, Linux x64, experimental)
+
+`pakstr build --target macos-arm64` packages the same `pakstr.yaml` app as `<appName>.app` in `<appId>-macos-arm64.zip` next to `build.out`. It runs on macOS only and downloads the pinned Electron release on first use. The app is ad-hoc signed and **not notarized**: Gatekeeper rejects it once downloaded, so it is for local testing only. App data lives in `~/Library/Application Support/<appId>`.
+
+`pakstr build --target windows-x64` writes `<appId>-windows-x64-setup.exe`, a per-user installer (no admin rights; installs to `%LOCALAPPDATA%\Programs\<appId>` with a Start menu shortcut and an uninstaller), and `<appId>-windows-x64.zip`, a portable `<appName>\<appName>.exe` folder. It builds on any host with [NSIS 3](https://nsis.sourceforge.io/) (`makensis`) on `PATH` (`brew install makensis`, `apt install nsis`, or the Windows NSIS installer). Both are **unsigned**, so SmartScreen warns before the first run. The numeric part of `versionName` becomes the Windows file version. App data lives in `%APPDATA%\<appId>` and survives uninstall.
+
+`pakstr build --target linux-x64` writes `<appId>-linux-x64.AppImage` and `<appId>-linux-x64.zip`, a portable `<appName>/<appId>` folder that keeps its executable bits. It builds on macOS or Linux (not Windows) with squashfs-tools 4.5+ (`mksquashfs`, `unsquashfs`) on `PATH` (`brew install squashfs`, `apt install squashfs-tools`), and downloads the pinned Electron release and AppImage runtime on first use. The icon comes from the same `logo.png` / `app.icon` lookup as Android. Running the AppImage needs FUSE 3, and Chromium's sandbox needs unprivileged user namespaces; Pakstr never turns the sandbox off, so distributions that restrict them (Ubuntu 23.10+) need an AppArmor profile or an administrator-installed package. App data lives in `~/.config/<appId>`.
+
+Desktop publishing and other platforms are not supported yet; `sign`, `publish`, and `run` remain Android-only.
+
 Delete commands are non-destructive by default. `--app` and `--publisher` are mutually exclusive, and Blossom HTTP deletion requires `--app --execute --delete-blobs`. NIP-09 is best-effort: relay acceptance does not prove physical erasure, and discovery is limited to events retained and returned by the configured relay.
 
 ---

package/android-template/app/build.gradle.kts

@@ -146,5 +146,6 @@ dependencies {
     implementation(libs.okhttp)
     implementation(libs.androidx.security.crypto)
     implementation(libs.zxing.core)
+    implementation(libs.androidx.webkit)
     implementation("org.bouncycastle:bcprov-jdk18on:1.78.1")
 }

package/android-template/app/src/androidTest/java/com/pakstr/app/PakstrWebBridgeTest.kt

@@ -0,0 +1,153 @@
+package com.pakstr.app
+
+import android.os.SystemClock
+import android.webkit.WebView
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assume.assumeTrue
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicInteger
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * Exercises the real androidx.webkit bridge: origin scoping, document-start
+ * injection, subframe rejection, and a full request/reply round trip.
+ * Pages are loaded with loadDataWithBaseURL so no LocalServer is needed.
+ */
+@RunWith(AndroidJUnit4::class)
+class PakstrWebBridgeTest {
+    private val instrumentation = InstrumentationRegistry.getInstrumentation()
+    private val handled = AtomicInteger()
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main)
+    private lateinit var webView: WebView
+
+    @Before
+    fun setUp() {
+        assumeTrue("WebView lacks the required androidx.webkit features", PakstrWebBridge.isSupported())
+        val providerScript = instrumentation.targetContext.assets.open("nip07.js")
+            .bufferedReader()
+            .use { it.readText() }
+        val installed = AtomicReference<Boolean>()
+        instrumentation.runOnMainSync {
+            webView = WebView(instrumentation.targetContext)
+            webView.settings.javaScriptEnabled = true
+            val router = WebMessageRouter(
+                handler = { method, _ ->
+                    handled.incrementAndGet()
+                    if (method == "runtime.getNip55CallbackUrl") CALLBACK else null
+                },
+                scope = scope,
+                runOnMain = { block -> webView.post { block() } }
+            )
+            installed.set(PakstrWebBridge.install(webView, router, providerScript) {})
+        }
+        assertEquals(true, installed.get())
+    }
+
+    @After
+    fun tearDown() {
+        scope.cancel()
+        if (::webView.isInitialized) {
+            instrumentation.runOnMainSync { webView.destroy() }
+        }
+    }
+
+    @Test
+    fun providerExistsBeforePageScriptsOnTheAppOrigin() {
+        load(
+            "${AppOrigin.ORIGIN}/",
+            "<script>document.title = [typeof window.nostr, typeof window.pakstr, " +
+                    "typeof window.AndroidBridge, typeof window.PakstrBridge].join(',')</script>"
+        )
+
+        assertEquals("object,object,undefined,undefined", awaitTitle())
+    }
+
+    @Test
+    fun foreignOriginsGetNeitherTheChannelNorTheProvider() {
+        for (base in listOf("https://example.com", "http://127.0.0.1:${Config.PORT + 1}", "http://localhost:${Config.PORT}")) {
+            // The origin in the title ties each result to the page that produced it.
+            load(
+                "$base/",
+                "<script>document.title = location.origin + '|' + [typeof window.nostr, typeof window.pakstr, " +
+                        "typeof window.${PakstrWebBridge.JS_OBJECT_NAME}].join(',')</script>"
+            )
+
+            assertEquals("$base|undefined,undefined,undefined", awaitTitle { it.startsWith("$base|") })
+        }
+    }
+
+    @Test
+    fun sameOriginSubframesGetNoProviderAndCannotReachNativeCode() {
+        val frame = "<script>" +
+                "const c = window.${PakstrWebBridge.JS_OBJECT_NAME};" +
+                "if (c) c.postMessage(JSON.stringify({ v: 1, id: 'frame', method: 'runtime.getNip55CallbackUrl' }));" +
+                "parent.document.title = 'frame:' + typeof window.nostr + ',' + typeof window.pakstr;" +
+                "</script>"
+        load("${AppOrigin.ORIGIN}/", "<iframe srcdoc=\"$frame\"></iframe>")
+
+        assertEquals("frame:undefined,undefined", awaitTitle())
+        SystemClock.sleep(1_000)
+        assertEquals(0, handled.get())
+    }
+
+    @Test
+    fun appTopFrameRequestsRoundTripThroughTheRouter() {
+        load(
+            "${AppOrigin.ORIGIN}/",
+            "<script>window.pakstr.getNip55CallbackUrl().then(" +
+                    "v => document.title = 'ok:' + v, e => document.title = 'err:' + e.error)</script>"
+        )
+
+        assertEquals("ok:$CALLBACK", awaitTitle())
+        assertEquals(1, handled.get())
+    }
+
+    private fun load(baseUrl: String, body: String) {
+        instrumentation.runOnMainSync {
+            webView.loadDataWithBaseURL(
+                baseUrl,
+                "<!doctype html><html><head><title></title></head><body>$body</body></html>",
+                "text/html",
+                "utf-8",
+                null
+            )
+        }
+    }
+
+    private fun awaitTitle(
+        timeoutMillis: Long = 10_000,
+        accept: (String) -> Boolean = { true }
+    ): String {
+        val deadline = SystemClock.uptimeMillis() + timeoutMillis
+        while (SystemClock.uptimeMillis() < deadline) {
+            val latch = CountDownLatch(1)
+            val title = AtomicReference<String>()
+            instrumentation.runOnMainSync {
+                webView.evaluateJavascript("document.title") { value ->
+                    title.set(value?.trim('"').orEmpty())
+                    latch.countDown()
+                }
+            }
+            latch.await(1, TimeUnit.SECONDS)
+            val current = title.get()
+            if (!current.isNullOrEmpty() && current != "null" && accept(current)) return current
+            SystemClock.sleep(100)
+        }
+        throw AssertionError("page did not set document.title in time")
+    }
+
+    private companion object {
+        const val CALLBACK = "pakstr-test://nip55-callback#nip55_event="
+    }
+}

package/android-template/app/src/main/assets/nip07.js

@@ -1,116 +1,166 @@
 (() => {
 
-    if (window.nostr) return;
+    // Installed by PakstrWebBridge as a document-start script for the app
+    // origin only, so it runs before any page script. The native side also
+    // rejects messages from subframes; only the top-level app document gets
+    // window.nostr and window.pakstr.
+    if (window.top !== window) return;
 
+    // Same limit as WebMessageRouter.MAX_MESSAGE_BYTES.
+    const MAX_MESSAGE_BYTES = 1024 * 1024;
+
+    // Injected by addWebMessageListener before this script runs.
+    const channel = window.__pakstrNative;
     const pending = new Map();
 
-    function callNative(method, payload) {
+    if (channel) {
+        channel.addEventListener("message", (event) => {
+            let response;
+            try {
+                response = JSON.parse(event.data);
+            } catch (_) {
+                return;
+            }
+            if (!response || response.v !== 1 || typeof response.id !== "string") return;
+
+            const p = pending.get(response.id);
+            if (!p) return;
+
+            pending.delete(response.id);
+
+            if (response.ok === true) {
+                p.resolve(response.result);
+            } else {
+                p.reject(response.error ?? {
+                    error: "SIGNER_ERROR",
+                    message: "Unknown signer error"
+                });
+            }
+        });
+    }
+
+    function callNative(method, params) {
         return new Promise((resolve, reject) => {
 
+            if (!channel) {
+                reject({
+                    error: "SIGNER_UNAVAILABLE",
+                    message: "Pakstr bridge is unavailable"
+                });
+                return;
+            }
+
             const id = crypto.randomUUID();
+            let message;
+            try {
+                message = JSON.stringify({ v: 1, id, method, params });
+            } catch (_) {
+                reject({ error: "SIGNER_ERROR", message: "Invalid request" });
+                return;
+            }
+            if (new TextEncoder().encode(message).length > MAX_MESSAGE_BYTES) {
+                reject({ error: "SIGNER_ERROR", message: "Request is too large" });
+                return;
+            }
 
             pending.set(id, {
                 resolve,
                 reject
             });
 
-            window.AndroidBridge.call(
-                method,
-                id,
-                payload ? JSON.stringify(payload) : ""
-            );
+            channel.postMessage(message);
         });
     }
 
-    window.__nostrResolve = (id, result) => {
+    if (!window.nostr) {
+        window.nostr = {
 
-        const p = pending.get(id);
-        if (!p) return;
+            getPublicKey: async () => {
+                return await callNative("nostr.getPublicKey");
+            },
 
-        pending.delete(id);
+            signEvent: async (event) => {
 
-        try {
-            const parsed = JSON.parse(result);
+                const result = await callNative(
+                    "nostr.signEvent",
+                    event
+                );
 
-            if (parsed.error) {
-                p.reject(parsed);
-                return;
-            }
+                return JSON.parse(result);
+            },
 
-        } catch (_) {
-            // Normal string response
-        }
+            nip04: {
 
-        p.resolve(result);
-    };
+                encrypt: async (pubkey, plaintext) => {
 
-    window.nostr = {
+                    return await callNative(
+                        "nostr.nip04_encrypt",
+                        {
+                            pubkey,
+                            plaintext
+                        }
+                    );
+                },
 
-        getPublicKey: async () => {
-            return await callNative("getPublicKey");
-        },
+                decrypt: async (pubkey, ciphertext) => {
 
-        signEvent: async (event) => {
+                    return await callNative(
+                        "nostr.nip04_decrypt",
+                        {
+                            pubkey,
+                            ciphertext
+                        }
+                    );
+                }
 
-            const result = await callNative(
-                "signEvent",
-                event
-            );
+            },
 
-            return JSON.parse(result);
-        },
+            nip44: {
 
-        nip04: {
+                encrypt: async (pubkey, plaintext) => {
 
-            encrypt: async (pubkey, plaintext) => {
+                    return await callNative(
+                        "nostr.nip44_encrypt",
+                        {
+                            pubkey,
+                            plaintext
+                        }
+                    );
+                },
 
-                return await callNative(
-                    "nip04_encrypt",
-                    {
-                        pubkey,
-                        plaintext
-                    }
-                );
-            },
+                decrypt: async (pubkey, ciphertext) => {
 
-            decrypt: async (pubkey, ciphertext) => {
+                    return await callNative(
+                        "nostr.nip44_decrypt",
+                        {
+                            pubkey,
+                            ciphertext
+                        }
+                    );
+                }
 
-                return await callNative(
-                    "nip04_decrypt",
-                    {
-                        pubkey,
-                        ciphertext
-                    }
-                );
             }
+        };
+    }
 
-        },
-
-        nip44: {
+    if (!window.pakstr) {
+        window.pakstr = {
 
-            encrypt: async (pubkey, plaintext) => {
+            version: 1,
 
-                return await callNative(
-                    "nip44_encrypt",
-                    {
-                        pubkey,
-                        plaintext
-                    }
-                );
+            getApiBaseUrl: async () => {
+                return await callNative("runtime.getApiBaseUrl");
             },
 
-            decrypt: async (pubkey, ciphertext) => {
+            setApiBaseUrl: async (url) => {
+                if (typeof url !== "string") return false;
+                return await callNative("runtime.setApiBaseUrl", { url });
+            },
 
-                return await callNative(
-                    "nip44_decrypt",
-                    {
-                        pubkey,
-                        ciphertext
-                    }
-                );
+            getNip55CallbackUrl: async () => {
+                return await callNative("runtime.getNip55CallbackUrl");
             }
+        };
+    }
 
-        }
-    };
-
-})();
+})();

package/android-template/app/src/main/java/com/pakstr/app/AppOrigin.kt

@@ -0,0 +1,77 @@
+package com.pakstr.app
+
+/**
+ * The web app's only trusted origin: the bundled LocalServer. The JavaScript
+ * bridge and the NIP-07 provider exist only in this origin's top-level frame.
+ *
+ * Checks take URI components (from android.net.Uri at the call site) so they
+ * stay plain Kotlin, and fail closed on anything unexpected.
+ */
+internal object AppOrigin {
+    private const val SCHEME = "http"
+    private const val HOST = "127.0.0.1"
+
+    /** Origin rule for androidx.webkit (exact scheme, host, and port; never a wildcard). */
+    val ORIGIN: String = "$SCHEME://$HOST:${Config.PORT}"
+
+    fun isTrustedOrigin(
+        scheme: String?,
+        host: String?,
+        port: Int,
+        userInfo: String?,
+        path: String?
+    ): Boolean =
+        isAppAuthority(scheme, host, port, userInfo) &&
+                (path.isNullOrEmpty() || path == "/")
+
+    /** Top-level navigation may only stay on the app origin (any path, query, or fragment). */
+    fun isNavigationAllowed(
+        scheme: String?,
+        host: String?,
+        port: Int,
+        userInfo: String?
+    ): Boolean = isAppAuthority(scheme, host, port, userInfo)
+
+    private fun isAppAuthority(
+        scheme: String?,
+        host: String?,
+        port: Int,
+        userInfo: String?
+    ): Boolean =
+        scheme == SCHEME &&
+                host == HOST &&
+                port == Config.PORT &&
+                userInfo == null
+}
+
+internal enum class NavigationDecision {
+    ALLOW,
+    BLOCK,
+    NIP55_SIGN_REQUEST,
+    REJECT_SUBFRAME_NIP55
+}
+
+/**
+ * shouldOverrideUrlLoading policy. `nostrsigner:` requests reach the signer
+ * only from the main frame; everything else must stay on the app origin.
+ */
+internal fun navigationDecision(
+    scheme: String?,
+    host: String?,
+    port: Int,
+    userInfo: String?,
+    isForMainFrame: Boolean
+): NavigationDecision {
+    if (scheme.equals("nostrsigner", ignoreCase = true)) {
+        return if (isForMainFrame) {
+            NavigationDecision.NIP55_SIGN_REQUEST
+        } else {
+            NavigationDecision.REJECT_SUBFRAME_NIP55
+        }
+    }
+    return if (AppOrigin.isNavigationAllowed(scheme, host, port, userInfo)) {
+        NavigationDecision.ALLOW
+    } else {
+        NavigationDecision.BLOCK
+    }
+}

package/android-template/app/src/main/java/com/pakstr/app/PakstrBridge.kt

@@ -1,22 +1,22 @@
 package com.pakstr.app
 
-import android.webkit.JavascriptInterface
-
+/**
+ * Native side of the `window.pakstr` runtime methods. Not exposed to
+ * JavaScript directly: WebMessageRouter calls it only for messages from the
+ * app origin's top-level frame.
+ */
 class PakstrBridge(
     private val runtimeApiBaseSettings: RuntimeApiBaseSettings
 ) {
 
-    @JavascriptInterface
     fun getNip55CallbackUrl(): String {
         return Nip55Callback.callbackPrefix
     }
 
-    @JavascriptInterface
     fun setApiBaseUrl(url: String): Boolean {
         return runtimeApiBaseSettings.setOverride(url)
     }
 
-    @JavascriptInterface
     fun getApiBaseUrl(): String? {
         return runtimeApiBaseSettings.current().url
     }

package/android-template/app/src/main/java/com/pakstr/app/PakstrWebBridge.kt

@@ -0,0 +1,89 @@
+package com.pakstr.app
+
+import android.webkit.WebView
+import androidx.annotation.UiThread
+import androidx.webkit.WebMessageCompat
+import androidx.webkit.WebViewCompat
+import androidx.webkit.WebViewFeature
+
+/**
+ * Installs the JavaScript bridge with androidx.webkit, scoped to
+ * [AppOrigin.ORIGIN]: the message channel object exists only in frames of
+ * that origin, and the NIP-07 provider script runs there at document start,
+ * before any page script. WebMessageRouter additionally drops messages from
+ * subframes and other origins.
+ *
+ * Fails closed: if the WebView lacks either feature, or installation fails,
+ * nothing is exposed and the page has no `window.nostr` or `window.pakstr`.
+ */
+internal object PakstrWebBridge {
+    const val JS_OBJECT_NAME = "__pakstrNative"
+
+    fun isSupported(): Boolean =
+        WebViewFeature.isFeatureSupported(WebViewFeature.WEB_MESSAGE_LISTENER) &&
+                WebViewFeature.isFeatureSupported(WebViewFeature.DOCUMENT_START_SCRIPT)
+
+    /** Must run before the page loads. Returns true only if both parts were installed. */
+    @UiThread
+    fun install(
+        webView: WebView,
+        router: WebMessageRouter,
+        providerScript: String,
+        logError: (String) -> Unit
+    ): Boolean {
+        // Nested, positive checks: lint accepts feature-gated calls only inside such guards.
+        if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_MESSAGE_LISTENER)) {
+            if (WebViewFeature.isFeatureSupported(WebViewFeature.DOCUMENT_START_SCRIPT)) {
+                val allowedOrigins = setOf(AppOrigin.ORIGIN)
+
+                try {
+                    WebViewCompat.addWebMessageListener(
+                        webView,
+                        JS_OBJECT_NAME,
+                        allowedOrigins
+                    ) { _, message, sourceOrigin, isMainFrame, replyProxy ->
+                        router.onMessage(
+                            MessageSource(
+                                scheme = sourceOrigin.scheme,
+                                host = sourceOrigin.host,
+                                port = sourceOrigin.port,
+                                userInfo = sourceOrigin.userInfo,
+                                path = sourceOrigin.path,
+                                isMainFrame = isMainFrame
+                            ),
+                            if (message.type == WebMessageCompat.TYPE_STRING) message.data else null
+                        ) { response ->
+                            try {
+                                replyProxy.postMessage(response)
+                            } catch (_: Exception) {
+                                // The frame is gone; nobody is waiting for this reply.
+                            }
+                        }
+                    }
+                } catch (error: Exception) {
+                    logError("Unable to install bridge channel: ${error.javaClass.simpleName}")
+                    return false
+                }
+
+                try {
+                    WebViewCompat.addDocumentStartJavaScript(
+                        webView,
+                        providerScript,
+                        allowedOrigins
+                    )
+                } catch (error: Exception) {
+                    try {
+                        WebViewCompat.removeWebMessageListener(webView, JS_OBJECT_NAME)
+                    } catch (_: Exception) {
+                        // Best effort; the WebView is not loaded yet either way.
+                    }
+                    logError("Unable to install NIP-07 provider: ${error.javaClass.simpleName}")
+                    return false
+                }
+                return true
+            }
+        }
+        logError("WebView lacks WEB_MESSAGE_LISTENER or DOCUMENT_START_SCRIPT; bridge disabled")
+        return false
+    }
+}