Move PR preview builds and hosting into Web Simulator

.github/workflows/checks.yml

@@ -29,10 +29,13 @@ jobs:
         run: npm ci --prefix web
       - name: Run simulator unit tests
         run: |
-          python3 web/tests/test-resolve-build-target.py
-          python3 web/tests/test-trigger-pr.py
+          for test in web/tests/test-*.py; do
+            if [[ "$test" == *test-browser-manifest.py ]]; then continue; fi
+            python3 "$test"
+          done
+      - name: Run build-independent JavaScript tests
+        run: |
           node web/tests/test-demo-data.mjs
-          python3 web/tests/test-inspector.py
           node web/tests/test-build-provenance.mjs
       - name: Install browser build dependencies
         run: |
@@ -45,6 +48,10 @@ jobs:
           path: specter-diy
           submodules: recursive
           persist-credentials: false
+      - name: Write and verify browser freeze manifest
+        run: |
+          python3 web/browser/write-browser-manifest.py "$GITHUB_WORKSPACE/specter-diy"
+          python3 web/tests/test-browser-manifest.py "$GITHUB_WORKSPACE/specter-diy"
       - name: Install Emscripten 3.1.74
         run: |
           git clone --depth 1 https://github.com/emscripten-core/emsdk.git "$RUNNER_TEMP/emsdk"

.preview-config/emsdk-commit

@@ -0,0 +1 @@
+3d6d8ee910466516a53e665b86458faa81dae9ba

.preview-config/virtual-host-commit

@@ -0,0 +1 @@
+3cf3ecd58a97da0f2cc4b7586ca33abf02f68372

README.md

@@ -1,20 +1,26 @@
-# Specter DIY web simulator
+# Specter DIY Web Simulator
 
-Browser simulator tooling for Specter DIY. It provides the WebAssembly build,
-simulated smartcard/SD-card/USB runtime, browser shell, provenance checks,
-and tests used by
-[`cryptoadvance/specter-diy`](https://github.com/cryptoadvance/specter-diy).
+This repository owns the browser simulator and the complete pull request preview
+service for Specter DIY. It builds the requested exact Specter source revision,
+builds matching firmware, runs firmware and browser tests, validates the
+resulting artifacts, hosts PR previews on this repository's GitHub Pages site,
+and keeps preview status and lifecycle state.
 
-The firmware repository resolves simulator `main` once per build, checks out
-that exact commit in its read-only build jobs, and runs the simulator scripts
-from that checkout. The exact Specter source and simulator commits are recorded
-in every browser build for provenance.
+Specter DIY only dispatches PR metadata to this paired repository, polls the
+public status JSON, and updates one local PR comment. It does not build or host
+the browser preview.
 
-See [the simulator workflow and release notes](docs/browser-simulator.md) for
-the repository contract and migration details.
+Start with [the manual build and setup guide](docs/browser-simulator.md). It
+covers local builds, paired forks, the narrow dispatch token, Pages setup, and
+the build/publisher security boundary.
 
-The official browser build and pull-request previews are published by the
-firmware repository at <https://cryptoadvance.github.io/specter-diy/>. To
-connect a running simulator to wallet software, use the
+The simulator runs the actual `src/` application from
+[`cryptoadvance/specter-diy`](https://github.com/cryptoadvance/specter-diy);
+this repository contains the browser shell, device shims, and build/test
+tooling, not another wallet implementation. For desktop integration use the
 [`cryptoadvance/specter-virtual-host`](https://github.com/cryptoadvance/specter-virtual-host)
-local bridge and its [latest release](https://github.com/cryptoadvance/specter-virtual-host/releases/latest).
+bridge at the immutable revision documented in `.preview-config/`.
+
+**Experimental development build. Never enter a real seed phrase or use real
+funds.** A PR preview contains code produced from an untrusted PR and executes
+in the visitor's browser.

web/browser/build-browser.sh

@@ -31,17 +31,7 @@ test "$(emcc --version | head -1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)"
 }
 
 python3 "$ROOT/browser/patch-source.py" "$SPECTER_SRC"
-cat > "$SPECTER_SRC/browser.manifest.py" <<'EOF'
-import os
-freeze('f469-disco/usermods/udisplay_f469/display_unixport')
-# Newer boards curate embit's src/ layout and omit CPython-only examples/tests.
-# Older board revisions had flat common libraries and no curated manifest.
-if os.path.isfile('f469-disco/manifests/common.py'):
-    include('f469-disco/manifests/common.py')
-else:
-    freeze('f469-disco/libs/common')
-freeze('src')
-EOF
+python3 "$ROOT/browser/write-browser-manifest.py" "$SPECTER_SRC"
 python3 "$ROOT/tests/test-browser-manifest.py" "$SPECTER_SRC"
 make -C "$SPECTER_SRC/f469-disco/micropython/mpy-cross" -j4 \
   CFLAGS_EXTRA="-Wno-dangling-pointer -Wno-enum-int-mismatch"

web/browser/replace_glue.py

@@ -1,13 +1,13 @@
 #!/usr/bin/env python3
-"""Replace PR-built Emscripten JavaScript with glue from trusted source."""
+"""Compose trusted Emscripten JavaScript with untrusted preview data files."""
 from hashlib import sha256
 from pathlib import Path
 import json
 import re
 import sys
 
 
-def replace_glue(root: Path, trusted_js: Path):
+def replace_glue(root: Path, trusted_js: Path, runtime_provenance: dict | None = None):
     root = root.resolve()
     if trusted_js.is_symlink() or not trusted_js.is_file():
         raise ValueError("Trusted Emscripten JavaScript artifact missing")
@@ -30,17 +30,24 @@ def replace_glue(root: Path, trusted_js: Path):
         raise ValueError("Build manifest missing")
     manifest = json.loads(manifest_path.read_text())
     artifacts = manifest.get("artifacts")
-    names = ("micropython.js", "micropython.wasm", "micropython.data")
-    if not isinstance(artifacts, dict) or set(artifacts) != set(names):
+    data_names = ("micropython.wasm", "micropython.data")
+    if not isinstance(artifacts, dict) or set(artifacts) != set(data_names):
         raise ValueError("Unexpected build artifacts")
-    for name in names:
+    for name in data_names:
         path = build / name
         if path.is_symlink() or not path.is_file():
             raise ValueError(f"Invalid build artifact: {name}")
-    (build / "micropython.js").write_bytes(js)
-    for name in names:
+    js_path = build / "micropython.js"
+    if js_path.exists() or js_path.is_symlink():
+        raise ValueError("Untrusted JavaScript was included in the browser payload")
+    js_path.write_bytes(js)
+    artifacts["micropython.js"] = {"bytes": len(js), "sha256": sha256(js).hexdigest()}
+    names = ("micropython.js", *data_names)
+    for name in data_names:
         data = (build / name).read_bytes()
         artifacts[name] = {"bytes": len(data), "sha256": sha256(data).hexdigest()}
+    if runtime_provenance is not None:
+        manifest["trusted_runtime"] = runtime_provenance
     artifact_set = sha256("".join(artifacts[name]["sha256"] for name in sorted(names)).encode()).hexdigest()
     manifest["artifact_set_sha256"] = artifact_set
     pointer["version"] = artifact_set[:16]

web/browser/site.js

@@ -76,6 +76,11 @@ let inspectorPending = null;
 let inspectorBaseline = null;
 let inspectorFileRequest = 0;
 let inspectorGeneration = -1;
+const virtualHostDetails = $('#virtual-host');
+const virtualHostStatus = $('#virtual-host-status');
+const virtualHostStatusText = $('#virtual-host-status-text');
+const virtualHostPreviewNote = $('#virtual-host-preview-note');
+const isolatedPreviewRoute = /(?:^|\/)pr\/\d+\/$/.test(siteRoot.pathname);
 let virtualHostSocket;
 let virtualHostRetryTimer;
 let virtualHostClientId = crypto.randomUUID?.() || `${Date.now()}-${Math.random().toString(16).slice(2)}`;
@@ -252,26 +257,50 @@ function setStatus(message, running = false) {
   status.textContent = message;
   dot.classList.toggle('on', running);
 }
-function updateVirtualHostStatus() {
+function updateVirtualHostStatus(message) {
   const bridge = $('#virtual-host-bridge-status');
   const wallet = $('#virtual-host-wallet-status');
-  if (!bridge || !wallet) return;
-  bridge.textContent = virtualHostRunning ? 'Running' : 'Stopped';
-  wallet.textContent = virtualHostWalletConnected ? 'Connected' : 'Waiting';
-  wallet.classList.toggle('waiting', !virtualHostWalletConnected);
+  if (bridge && wallet) {
+    bridge.textContent = virtualHostRunning ? 'Running' : 'Stopped';
+    wallet.textContent = virtualHostWalletConnected ? 'Connected' : 'Waiting';
+    wallet.classList.toggle('waiting', !virtualHostWalletConnected);
+  }
+  if (!virtualHostStatus || !virtualHostStatusText) return;
+  const connected = virtualHostRunning && virtualHostWalletConnected;
+  virtualHostStatus.classList.toggle('connected', connected);
+  virtualHostStatus.classList.toggle('waiting', !connected);
+  if (message) {
+    virtualHostStatusText.textContent = message;
+  } else if (isolatedPreviewRoute) {
+    virtualHostStatusText.textContent = 'Local Virtual Host connections are disabled on isolated pull-request previews.';
+  } else if (!virtualHostRunning) {
+    virtualHostStatusText.textContent = 'Virtual Host not detected — run it on this computer to connect.';
+  } else if (!virtualHostWalletConnected) {
+    virtualHostStatusText.textContent = 'Virtual Host is running — waiting for Specter Desktop.';
+  } else {
+    virtualHostStatusText.textContent = 'Connected to Specter Desktop.';
+  }
+}
+function scheduleVirtualHostRetry() {
+  clearTimeout(virtualHostRetryTimer);
+  if (isolatedPreviewRoute || (!virtualHostDetails?.open && params.get('virtual-host') !== '1')) return;
+  virtualHostRetryTimer = setTimeout(connectVirtualHost, 2000);
 }
 function connectVirtualHost() {
-  if (!$('#virtual-host') || params.get('virtual-host') !== '1' ||
+  if (isolatedPreviewRoute) {
+    updateVirtualHostStatus();
+    return;
+  }
+  if (!virtualHostDetails || (params.get('virtual-host') !== '1' && !virtualHostDetails.open) ||
       virtualHostSocket?.readyState === WebSocket.OPEN || virtualHostSocket?.readyState === WebSocket.CONNECTING) return;
   const query = `?client=${encodeURIComponent(virtualHostClientId)}`;
   const localPage = location.hostname === '127.0.0.1' && location.port === '8788';
   let socket;
   try {
     socket = new WebSocket(`${localPage ? `ws://${location.host}` : 'ws://127.0.0.1:8788'}/bridge${query}`);
   } catch (error) {
-    log(`Virtual Host unavailable: ${error.message}`);
-    clearTimeout(virtualHostRetryTimer);
-    virtualHostRetryTimer = setTimeout(connectVirtualHost, 2000);
+    updateVirtualHostStatus(`Virtual Host unavailable: ${error.message}`);
+    scheduleVirtualHostRetry();
     return;
   }
   virtualHostSocket = socket;
@@ -302,10 +331,7 @@ function connectVirtualHost() {
     virtualHostRunning = false;
     virtualHostWalletConnected = false;
     updateVirtualHostStatus();
-    if (event.code !== 4001 && params.get('virtual-host') === '1') {
-      clearTimeout(virtualHostRetryTimer);
-      virtualHostRetryTimer = setTimeout(connectVirtualHost, 2000);
-    }
+    if (event.code !== 4001) scheduleVirtualHostRetry();
   };
   socket.onerror = () => { /* onclose updates the status and schedules a retry */ };
 }
@@ -314,6 +340,14 @@ addEventListener('specter-virtual-host-send', event => {
   const bytes = event.detail;
   if (bytes instanceof ArrayBuffer || ArrayBuffer.isView(bytes)) virtualHostSocket.send(bytes);
 });
+if (virtualHostDetails) {
+  virtualHostDetails.addEventListener('toggle', () => {
+    if (virtualHostDetails.open) connectVirtualHost();
+    else if (params.get('virtual-host') !== '1') clearTimeout(virtualHostRetryTimer);
+  });
+  if (virtualHostPreviewNote) virtualHostPreviewNote.hidden = !isolatedPreviewRoute;
+  updateVirtualHostStatus();
+}
 function clearStartupTimer() {
   if (startupTimer !== undefined) clearTimeout(startupTimer);
   startupTimer = undefined;
@@ -1191,7 +1225,7 @@ function updateBuildMetadata(manifest) {
 
 try {
   if (params.get('virtual-host') === '1' && !embedded && !gallery) {
-    $('#virtual-host').hidden = false;
+    virtualHostDetails.open = true;
     connectVirtualHost();
   }
   stateFiles = await awaitPeripherals();

web/browser/write-browser-manifest.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Write the trusted frozen-module manifest into a Specter source checkout."""
+from pathlib import Path
+import sys
+
+
+MANIFEST = '''import os
+freeze('f469-disco/usermods/udisplay_f469/display_unixport')
+# Newer boards curate embit's src/ layout and omit CPython-only examples/tests.
+# Older board revisions had flat common libraries and no curated manifest.
+if os.path.isfile('f469-disco/manifests/common.py'):
+    include('f469-disco/manifests/common.py')
+else:
+    freeze('f469-disco/libs/common')
+freeze('src')
+'''
+
+
+def write_manifest(source: Path) -> Path:
+    source = source.resolve()
+    if not source.is_dir():
+        raise ValueError("Specter source directory does not exist")
+    manifest = source / "browser.manifest.py"
+    if manifest.is_symlink():
+        raise ValueError("Browser manifest path must not be a symlink")
+    manifest.write_text(MANIFEST, encoding="utf-8")
+    return manifest
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        raise SystemExit("Usage: write-browser-manifest.py SPECTER_SOURCE_DIR")
+    write_manifest(Path(sys.argv[1]))