pakstr 0.29.1 → 0.31.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.*
@@ -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/src/debug/AndroidManifest.xml

@@ -1,6 +1,9 @@
 <?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android">
-    <application>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+    <application
+        android:memtagMode="sync"
+        tools:replace="android:memtagMode">
         <activity-alias
             android:name=".debug.DeveloperToolsDebugLauncher"
             android:enabled="true"

package/android-template/app/src/main/AndroidManifest.xml

@@ -23,6 +23,7 @@
         android:fullBackupContent="@xml/backup_rules"
         android:icon="@mipmap/ic_launcher"
         android:label="@string/app_name"
+        android:memtagMode="async"
         android:networkSecurityConfig="@xml/network_security_config"
         android:roundIcon="@mipmap/ic_launcher_round"
         android:supportsRtl="true"

package/desktop-runtime/README.md

@@ -0,0 +1,108 @@
+# Pakstr desktop runtime
+
+Electron runtime that hosts a Pakstr web app on desktop, mirroring the Android
+shell's contracts. `pakstr build --target macos-arm64|windows-x64|linux-x64`
+stages this bundle with the app (`src/desktop/` in the CLI); the bundle ships
+in the CLI's npm package. All targets package the same bundle; only the menu
+differs (`src/appMenu.js`).
+
+## Build
+
+```sh
+npm --prefix packages/cli ci
+npm --prefix packages/cli run build   # tsc, then bundles dist/main.js and dist/preload.js
+```
+
+`npm --prefix packages/cli/desktop-runtime install` is only needed to run the
+runtime unpackaged with the `electron` dev binary.
+
+`dist/main.js` and `dist/preload.js` are self-contained: only `electron` and
+Node built-ins are left external (the build fails otherwise), so a generated
+app needs no `node_modules`. Third-party code and `src/shared` come from the
+CLI package. The `debug` package is compiled out because applesauce logs
+NIP-46 request params through it.
+
+## Generated app layout
+
+```
+<appRoot>/package.json          "main" -> the bundled main.js (preload.js beside it)
+<appRoot>/pakstr-desktop.json   { "appId": "com.example.app", "appName": "Example" }
+<appRoot>/web/                  staged web assets, incl. pakstr-runtime.json
+```
+
+## Behaviour
+
+- The app is served from `pakstr://app` (standard, secure scheme) with the
+  Android SPA fallback. `/api/*` is proxied to the effective API base
+  (persisted override, then packaged `apiBase`, then disabled). API cookies
+  live in the session cookie jar and never reach the renderer, and neither
+  do `Set-Cookie` or `Location`. Redirects are not followed.
+- NIP-98: `X-Forwarded-Host: app` / `X-Forwarded-Proto: pakstr` are added
+  only when the event's unique `u` tag is exactly the local request URL.
+- `window.nostr` (plain and writable, like `nip07.js`) and the synchronous
+  `window.PakstrBridge.getApiBaseUrl()` / `setApiBaseUrl(url)` exist only in
+  the main window's `pakstr://app` top frame. The first `window.nostr` call
+  without a signer opens a `nostrconnect://` pairing prompt that uses the
+  strict `src/shared/nip46Pairing` module.
+- All renderers are sandboxed with context isolation. Top-level navigation
+  stays on `pakstr://app`, `window.open` is denied, and web permissions are
+  denied except clipboard write and fullscreen. DevTools are available only
+  when unpackaged, and a packaged app exits if launched with a
+  remote-debugging or certificate-bypass switch. The runtime never disables
+  Chromium's sandbox.
+- All data (cookies, storage, API base override) lives in
+  `<appData>/<appId>`. The Electron app name is also the appId, because it
+  names the keychain item holding the cookie-encryption key ("<name> Safe
+  Storage"): renaming `appName` keeps sessions. The macOS menu shows `appName`.
+
+## Windows: not yet verified on a Windows machine
+
+Windows packages are cross-built and checked structurally (executable
+metadata, fuses, asar integrity, portable ZIP contents, NSIS output), but
+nothing here runs them. Before relying on `windows-x64`, check on real Windows
+10/11 x64:
+
+- The installer runs without admin rights. The Start menu shortcut, the
+  Apps & features entry, and the finish-page launch work, and uninstalling
+  removes everything except `%APPDATA%\<appId>`.
+- Reinstalling or upgrading over a running app prompts to close it, and an
+  upgrade that renames `appName` leaves no old `.exe` or shortcut behind.
+- The portable ZIP runs after extraction, including from a path with spaces
+  or non-ASCII characters.
+- The app starts with the asar-integrity and `OnlyLoadAppFromAsar` fuses on.
+  `pakstr://app` loads, `/api` proxying, cookies (DPAPI), `window.nostr`,
+  NIP-46 pairing, and signer auth links work, and a second launch focuses the
+  first window.
+- Taskbar pinning: Electron's default AppUserModelID may not match the
+  installer's shortcut (it has no AUMID), so a pin from the Start menu can
+  show as a separate taskbar button.
+- SmartScreen shows the unsigned-publisher warning; there is no Authenticode
+  signing yet.
+
+## Linux: not yet verified on a Linux machine
+
+Linux packages are cross-built and checked structurally (pinned AppImage
+runtime, root-owned squashfs with exact modes, desktop entry, icon, portable
+ZIP modes, fuses, asar hashes), but nothing here runs them. Electron enforces
+embedded asar integrity on macOS and Windows only, so on Linux the read-only
+AppImage filesystem and the build-time checks are what protect `app.asar`.
+Before relying on `linux-x64`, check on real x64 distributions (e.g. Ubuntu
+22.04 and 24.04, Fedora, Debian 12):
+
+- The AppImage starts with FUSE 3 (`fusermount3`), and with
+  `--appimage-extract-and-run` without FUSE; the portable ZIP runs after
+  `unzip`, including from a path with spaces.
+- Chromium's sandbox: with unprivileged user namespaces available the app
+  starts sandboxed. Where they are restricted (Ubuntu 23.10+ AppArmor) it
+  is expected to abort rather than run unsandboxed; record the message. The
+  runtime never passes `--no-sandbox`, and `chrome-sandbox` is not setuid.
+- `pakstr://app` loads, `/api` proxying, `window.nostr`, NIP-46 pairing, and
+  signer auth links (`xdg-open`) work, and a second launch focuses the first
+  window.
+- Cookies are encrypted with the desktop keyring (Secret Service / KWallet);
+  without one, Chromium falls back to a fixed key, so check which backend is
+  used.
+- The window class / Wayland app id is the appId, so desktop integration
+  (AppImageLauncher, appimaged) groups the window with the desktop entry and
+  shows the icon. Required system libraries (GTK 3, NSS, libgbm, ALSA, ...)
+  are those of any Chromium build and are not bundled.