diff --git a/.env.example b/.env.example index eea2c6be4..1570190bd 100644 --- a/.env.example +++ b/.env.example @@ -6,6 +6,17 @@ VITE_APP_URL= # https://polkadot.com/get-started/polkadot-for-desktop. VITE_DESKTOP_DOWNLOAD_URL= +# Optional host-owned background receiving. Set both or leave both empty +# (unsupported). HTTPS only; PUSH_ORIGIN is this host's exact origin and must +# equal the relay's PUSH_ORIGIN. No private provider keys belong in VITE_*. +# VITE_RECEIVING_RELAY_URL=https:/// (optional base path) +# VITE_RECEIVING_PUSH_ORIGIN=https:// (no trailing slash) +VITE_RECEIVING_RELAY_URL= +VITE_RECEIVING_PUSH_ORIGIN= +# Public base64url VAPID application-server key supplied by the relay operator. +# Required for user-click Web Push enrollment, never the private VAPID key. +VITE_RECEIVING_VAPID_PUBLIC_KEY= + # Required. Comma-separated networks this build offers in the Settings # selector. Each value must match a `NetworkName` in # `packages/config/src/network.ts`. diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index eb109577e..8009a3378 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -130,6 +130,9 @@ jobs: VITE_SENTRY_DSN: ${{ secrets.SENTRY_DSN }} VITE_METRICS: ${{ secrets.VITE_METRICS }} VITE_NETWORKS: ${{ vars.NETWORKS }} + VITE_RECEIVING_RELAY_URL: ${{ vars.RECEIVING_RELAY_URL }} + VITE_RECEIVING_PUSH_ORIGIN: ${{ vars.RECEIVING_PUSH_ORIGIN }} + VITE_RECEIVING_VAPID_PUBLIC_KEY: ${{ vars.RECEIVING_VAPID_PUBLIC_KEY }} SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }} - uses: webfactory/ssh-agent@e83874834305fe9a4a2997156cb26c5de65a8555 # v0.10.0 @@ -138,6 +141,27 @@ jobs: - run: ssh-keyscan ${{ secrets.DEPLOY_HOST }} >> ~/.ssh/known_hosts + # Receiving needs the worker CSP generated by this build, so nginx follows the frontend build when opted in. + - name: Deploy receiving nginx config + if: vars.DEPLOY_NGINX == 'true' && vars.RECEIVING_RELAY_URL != '' + run: | + set -euo pipefail + case "$DEPLOY_SITE" in + paseo.li) NGINX_ENV=paseo ;; + paseoli.dev) NGINX_ENV=dev-paseo ;; + paseo.fyi) NGINX_ENV=fyi-paseo ;; + testnet.li) NGINX_ENV=dev-test ;; + *) echo "::error::No Makefile ENV for $DEPLOY_SITE"; exit 1 ;; + esac + make deploy-nginx ENV="$NGINX_ENV" REMOTE="$DEPLOY_USER@$DEPLOY_HOST" + env: + DEPLOY_SITE: ${{ matrix.environment }} + DEPLOY_USER: ${{ secrets.DEPLOY_USER }} + DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }} + SENTRY_DSN: ${{ secrets.SENTRY_DSN }} + RECEIVING_CSP_FILE: apps/host/dist/host-receiving-csp.conf + RECEIVING_PUSH_ORIGIN: ${{ vars.RECEIVING_PUSH_ORIGIN }} + RECEIVING_PROXY_PORT: ${{ vars.RECEIVING_PROXY_PORT }} - name: Deploy run: make ci-deploy env: diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 2849d6a77..e9c24dbda 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -144,6 +144,112 @@ deploys the PR head SHA after the quality gate. Do not use `workflow_dispatch` f **westendli.dev**, not paseo.fyi. Do not fall back to another environment if paseo.fyi qualification or deployment fails. +## Optional browser background receiving + +Receiving is host-owned and opt-in. It is unsupported when both build settings are absent; a partial configuration fails +the build. There is no default relay or provider credential: + +```dotenv +VITE_RECEIVING_RELAY_URL=https://relay.example.org +VITE_RECEIVING_PUSH_ORIGIN=https://browser-smoke.receiving.test +VITE_RECEIVING_VAPID_PUBLIC_KEY= +``` + +These are illustrative addresses, not deployed services. Use the approved relay and product-subdomain host origins. Set +both variables for the host build (or leave both empty). URLs must use HTTPS without credentials, query strings, or +fragments. The push origin must equal the actual product host's `location.origin`, without a trailing slash, and the +relay's `PUSH_ORIGIN`. For the local HTTPS qualification route this is exactly `https://browser-smoke.receiving.test`, +not the root landing page `https://receiving.test`, the protocol iframe origin, or a `/product` path. The root landing +page does not expose the product host Settings. Configure the relay's allowed origin/product for that same route. The +relay must allow that origin through CORS and expose the canonical receiving transport endpoints. Set +`VITE_RECEIVING_VAPID_PUBLIC_KEY` to the relay operator's public base64url VAPID application-server key to enable +user-click Web Push enrollment. When omitted, enrollment reports an unsupported configuration; the key is not guessed or +fetched from an unrelated provider. Keep VAPID private keys and provider credentials on the relay; never put them in +`VITE_*`, product frames, or a notification payload. Existing build/deployment environments do not acquire these +settings automatically. + +For GitHub deployments, set the environment-scoped `RECEIVING_RELAY_URL`, `RECEIVING_PUSH_ORIGIN`, and +`RECEIVING_VAPID_PUBLIC_KEY`; the workflow passes them to the corresponding `VITE_*` build settings. Enable +`DEPLOY_NGINX` so the same deployment runs `make deploy-nginx` with the worker CSP generated by that build. Dist-only +upload does not update nginx policy. + +For a loopback relay exposed at the configured product origin's `/__receiving`, also set `RECEIVING_PROXY_PORT` to its +listening port. The nginx deployment requires the matching generated CSP and an HTTPS product subdomain of the +deployment site. Only that exact hostname can reach the relay; other product hosts receive 404. The relay owns CORS, and +receiving request paths are excluded from nginx access logs. With no proxy port, `/__receiving/` returns 404. The relay +and its persistent private keys/database must already be provisioned; the frontend workflow never creates or rotates +provider credentials. + +The vendored `@parity/truapi-host` JS, generated bindings, and PVM web WASM must have compatible receiving-enabled +contracts and exact recorded source provenance. Required exports are `browser-receiving-worker` and +`WasmNotificationReceiver` from `wasm/web`. This top integration vendors both SDK archives and upstream's standard +`wasm/web` (runtime) and `wasm/testing` (local wallet signing worker) bundles from native #1011 at +`e48777643c52278769a6bac724c7f6577cb87197`. Archive and generated client/WASM checksums are recorded in +`vendor/truapi-host.lock.json`; the only package override is the host SDK's local `@parity/truapi` dependency. A clean +#185-based receiving distribution needs its own SDK without Chat/Seity/Jam; never reuse this top integration artifact +downward. The build bundles `host-receiving.js` as a standalone classic IIFE and copies that SDK's WASM to a +content-hashed, same-origin `assets/receiving-.wasm`. No dynamic imports or second service-worker registration +are used. The canonical installer owns callback SCALE adaptation. Workbox imports this bundle into `/host-sw.js`, +retains its existing precache rules and prompted update behavior, and precaches the matching WASM. Deploy the complete +host output together, not a worker or WASM file in isolation. + +For CSP-enforcing hosting, the build also emits `host-receiving-csp.conf`, an nginx `add_header` directive with the +exact relay origin. `deploy-nginx` installs this file as the site-specific `dotli-receiving-csp.conf` when +`RECEIVING_CSP_FILE` is set; `/host-sw.js` includes it alongside its existing headers. The CI workflow sets this path +from the matching configured host build. An unconfigured nginx deployment reinstalls the empty policy rather than +retaining an old relay. It permits only same-origin scripts, WASM compilation (`'wasm-unsafe-eval'`), and connections to +self/the configured relay. Install the matching policy whenever the relay changes; do not copy a policy between +environments. If an existing page CSP is enforced by a proxy, preserve its other directives while permitting +`worker-src 'self'` and the configured relay in `connect-src`. HTML meta policies do not set a service worker's CSP. +Static hosting other than nginx must translate the generated policy into the `/host-sw.js` response header. + +Receiving requires HTTPS, service workers, Push API, Notifications, IndexedDB, and Web Locks. A configured build still +requires separate host receiving consent and OS notification permission. A host-origin mismatch or unavailable Web Locks +leaves receiving unsupported without breaking Workbox shell updates. The host announces registration through +`dotli:receiving-registration`; late-mounting UI looks up that same registration instead of registering another worker. +Development servers do not install this production receiving worker: exercise receiving with a built host served over +the approved HTTPS origin. + +The shell exposes **Background receiving** in Settings. Enabling Web Push must come from that button's user gesture; it +does not enroll products. Enrollment requires a separate trusted host consent prompt. Revoke all receiving disables the +durable registrations locally before any asynchronous relay synchronization. Explicit disconnect, wallet erase, network +replacement, and full reset use the same local-first fence. A full reset retains the receiver's durable revocation +ledger so pending remote deletions are not lost; ordinary product close, page close, and suspension do not erase consent +or enrollments. + +Local Chromium qualification exercised the built host at `https://browser-smoke.receiving.test`: Settings enabled a real +provider subscription through the button, with exactly one root-scoped `/host-sw.js`; the receiving UI reported enabled +and the revoke control completed without browser errors. Notification permission was supplied through the isolated +browser's automation grant. This was host transport setup, not a verified product enrollment—the smoke product name was +intentionally not published. UI typechecking, 43 notification/session-storage tests and 45 host tests pass. Physical +mobile delivery and end-to-end activation in a deployed product remain separate qualification gates. + +Only the native core's authenticated `identityAccountId` can select an account. The host independently runs the existing +CID content verifier, off the ordinary startup and messaging path, before using a validated SHA-256 root multihash as +the artifact identity. This applies equally to HTML and PolkaVM archives. URL/development products, unsupported CID +provenance, and missing authenticated identity report receiving unsupported. Product frames never supply receiving +authority. Each connection retains its initial account/artifact/environment snapshot and is fenced on host navigation or +account replacement. + +Notification activation only focuses or opens the host-retained verified product descriptor in the already selected +unlocked account. It never unlocks, switches accounts, or follows a sender route as a URL. Once that execution is ready, +the shared worker queues the canonical notification Activation event for the product to consume. + +### Publication and qualification gates + +This is local source work, not a published SDK or an approved rollout. Before publication, record accessible source +revisions, archive hashes, and separate WASM provenance in the vendor lock; preserve the clean feature/integration +boundaries. Obtain explicit approval for the exact publication and deployment environment; a local successful build does +not authorize either. + +After matching artifacts are available, run UI typechecks and receiving tests, then build with the exact +product-subdomain origin, relay URL, and public VAPID key. Qualify Settings enable/permission denial/revoke, explicit +product consent, authenticated account/artifact binding, account replacement fences, and the root-scoped `/host-sw.js` +on that origin. Demonstrate actual provider delivery with no open host page, deduplication, and safe activation after +readiness. Provider acceptance alone is not notification display; unsupported/unconfigured states and local-first +revocation during relay failure must remain visible. Do not infer mobile or fully-quit browser delivery from a worker +smoke test. + ## Checking what is deployed Every origin serves its own build's `host_version.json` at the root: diff --git a/Makefile b/Makefile index 2b972e62b..814d04fad 100644 --- a/Makefile +++ b/Makefile @@ -109,6 +109,10 @@ deploy: _require-env build ssh $(REMOTE_TARGET) 'sudo install -d -m 0755 -o $$(whoami) -g $$(id -gn) $(REMOTE_PATH) $(REMOTE_PATH)/host $(REMOTE_PATH)/app $(REMOTE_PATH)/protocol' $(call _rsync_dist,$(REMOTE_TARGET),$(REMOTE_PATH)) +# Optional receiving policy and same-origin relay. Credentials stay in the relay. +RECEIVING_CSP_FILE ?= +RECEIVING_PUSH_ORIGIN ?= +RECEIVING_PROXY_PORT ?= # A literal "#" goes through _hash because make >= 4.3 keeps the backslash of a "\#" inside a function call. _hash := \# _nginx_render = DOMAIN='$(SITE_$(ENV))' WEBROOT='$(DEPLOY_PATH_$(ENV))' \ @@ -133,9 +137,33 @@ deploy-nginx: _require-env $(_sentry_warn) $(eval REMOTE_TARGET := $(or $(REMOTE),$(REMOTE_FOR_$(ENV)))) $(eval SITE := $(SITE_$(ENV))) - $(_nginx_render) > /tmp/$(SITE).nginx - rsync -avz --delete $(if $(SENTRY_DSN),,--exclude=dotli-sentry-tunnel.conf --delete-excluded) nginx/snippets/ $(REMOTE_TARGET):/tmp/dotli-nginx-snippets/ - scp /tmp/$(SITE).nginx $(REMOTE_TARGET):/tmp/$(SITE).nginx + @set -eu; \ + stage=$$(mktemp -d); \ + trap 'rm -rf "$$stage"' EXIT; \ + $(_nginx_render) > "$$stage/$(SITE).nginx"; \ + mkdir "$$stage/snippets"; \ + for snippet in nginx/snippets/*.conf; do \ + if [ -z "$(SENTRY_DSN)" ] && [ "$${snippet##*/}" = dotli-sentry-tunnel.conf ]; then continue; fi; \ + cp "$$snippet" "$$stage/snippets/$${snippet##*/}"; \ + done; \ + if [ -n "$(RECEIVING_CSP_FILE)" ]; then \ + test -s "$(RECEIVING_CSP_FILE)" || { echo "Receiving CSP must come from the matching host build"; exit 1; }; \ + cp "$(RECEIVING_CSP_FILE)" "$$stage/snippets/dotli-receiving-csp.conf"; \ + fi; \ + if [ -n "$(RECEIVING_PROXY_PORT)" ]; then \ + test -n "$(RECEIVING_CSP_FILE)" || { echo "Receiving proxy requires its matching worker CSP"; exit 1; }; \ + port='$(RECEIVING_PROXY_PORT)'; \ + case "$$port" in *[!0-9]*) echo "Receiving proxy port must be numeric"; exit 1 ;; esac; \ + test "$$port" -ge 1 && test "$$port" -le 65535 || { echo "Invalid receiving proxy port"; exit 1; }; \ + origin='$(RECEIVING_PUSH_ORIGIN)'; \ + case "$$origin" in https://*.$(SITE)) ;; *) echo "Receiving origin must be a product host of $(SITE)"; exit 1 ;; esac; \ + host=$${origin#https://}; \ + case "$$host" in *[!a-z0-9.-]*) echo "Invalid receiving product hostname"; exit 1 ;; esac; \ + RECEIVING_HOST="$$host" RECEIVING_PORT="$$port" envsubst '$$RECEIVING_HOST $$RECEIVING_PORT' \ + < nginx/receiving-proxy.conf.template > "$$stage/snippets/dotli-receiving-proxy.conf"; \ + fi; \ + rsync -avz --delete "$$stage/snippets/" $(REMOTE_TARGET):/tmp/dotli-nginx-snippets/; \ + scp "$$stage/$(SITE).nginx" $(REMOTE_TARGET):/tmp/$(SITE).nginx ssh $(REMOTE_TARGET) 'sudo install -d -m 0755 /etc/nginx/snippets && sudo rsync -av /tmp/dotli-nginx-snippets/ /etc/nginx/snippets/ && sudo cp /tmp/$(SITE).nginx /etc/nginx/sites-available/$(SITE) && sudo ln -sf /etc/nginx/sites-available/$(SITE) /etc/nginx/sites-enabled/$(SITE) && sudo nginx -t && sudo systemctl reload nginx' # Protocol first: a new shell waits for the iframe's `listening` signal, which an older iframe never sends. diff --git a/README.md b/README.md index 509f99937..4ddbf4a00 100644 --- a/README.md +++ b/README.md @@ -139,6 +139,38 @@ traffic stays on the bounded PolkaVM runtime ABI 1. Guest Host requests use the Host-frame bytes use the canonical TrUAPI wire codec, currently version 3. Build guest clients against the SDK recorded in `vendor/truapi-host.lock.json`; runtime ABI 1 compatibility alone does not imply TrUAPI wire compatibility. +On this branch, `vendor/truapi-host.lock.json` pins the canonical SDK and Wasm to `feat/jam-peer-transport-on-seity`. +JAM peer transport is execution-local in the sandbox. Before dialing a network, it requests `JamPeers` permission +through the product's authenticated port to the shared page core. The host's Solid permission dialog shows the full +genesis hash and offers **Allow once**, **Always allow**, and **Deny**; dismissal saves no decision. Durable decisions +are scoped to product and genesis, while a one-time grant lasts only for that execution. This grants no account, +signing, storage, or arbitrary web access. Peer access permits sending and receiving messages; it is not a read-only +network permission. JAM permission callbacks return the decision without an administrative permission write, leaving the +canonical Rust core to persist it against the pending product/genesis request. Administrative settings changes remain a +separate operation that deliberately invalidates stale consent. + +The sandbox checks for the required browser WebTransport capability before requesting permission. If it is unavailable, +the host leaves the stored permission unchanged, shows the detected browser version and compatibility requirements, and +the app can continue with its verified snapshot. Supported versions are Chrome or Edge 100+, Firefox 125+, and +Safari/iOS 26.4+. + +The canonical session uses WebTransport to app-selected peers, with at most eight pending or established connections, +sixteen streams per connection, and 1 MiB messages. Permission waits consume a connection slot before prompting. Each +execution remembers at most eight distinct genesis decisions, including pending, refused, and dismissed decisions. A new +ninth genesis returns `Limit`; existing decisions are not evicted or re-prompted. Cancellation releases its pending dial +slot but retains the bounded network decision. Received data remains unverified until the guest checks it. The runtime +menu's **Network access** section lists this execution's grants. Network updates continue while its display/audio menu +is paused. Stop, replacement, and runtime failure close the session and refuse outstanding permission requests; a +replacement guest cannot consume old replies. Ordinary host frames retain their 1 MiB bound and still use the shared +page core; only peer frames use the larger bound needed for message framing. The session's ten-second dial deadline +includes the permission prompt: a late decision does not resurrect an expired dial, though a retry can use the +remembered decision. + +The full genesis scopes permission decisions, but the browser WebTransport handshake does not bind the peer to that +genesis. The current PolkaJAM HTTP/3 CONNECT endpoint does not negotiate a genesis. TLS pins an app-supplied peer key; +it does not prove validator membership. The guest must verify chain data. Browser support is retained with this explicit +limitation; no manifest declaration or invented URL/protocol parameter substitutes for verification. + App manifest v2 uses runtime ABI 1 with framebuffer, Tri2D, WebGPU Raster, and bounded capability negotiation; TrUAPI, MotionSample v1, text, IME, focus, and wheel input use the same pinned browser runtime as native Hosts. UI output v1 applies cursor and IME-agent state in the sandbox. Clipboard text and HTTP(S) navigation cross an origin-checked parent @@ -304,6 +336,16 @@ Loaded SPAs communicate with dotli through a postMessage-based protocol. The bri | `connectionStatus` | Streams auth state changes to the SPA | | `chat.*` | Product chat: rooms and messages persisted locally, rendered in the topbar chat panel | +### Permission decision ownership + +Core-initiated permission callbacks return the user's decision without writing the grant. The canonical core commits +that decision against the permission revision it captured before prompting; an adapter-side write would invalidate the +pending request. Host-initiated mediated-device prompts still persist their own durable decisions. + +After a committed permission change, the bridge matches the canonical product identity and refreshes the active iframe's +Permissions Policy. It replaces the iframe only if that policy changes. Notification approval therefore keeps the +requesting execution alive; grants that change iframe access reload it, and stale executions cannot trigger reloads. + A fresh product-document handshake retires the previous native execution before attaching its replacement. Pending permission prompts and execution-local grants cannot cross that boundary; repeated readiness messages with the same connection identifier remain idempotent. Connection creation is single-flight, and a superseded result is closed rather @@ -322,6 +364,10 @@ activation feed, which belongs to the separate generic notification feature. The to the product execution, authenticated account, network and artifact, and another product, account, network or artifact cannot read them. +Notification authority follows live native auth transitions, not the UI-state cache or shared-session storage hints. An +unchanged stored-session reload emits no new auth transition and leaves ordinary notifications usable. A native account +change, disconnection or explicit logout invalidates the previous scope. + Direct-iframe products, including localhost previews, use the same permission and account gates. Because their mutable URLs do not identify verified executable content, each execution receives a fresh artifact identity. Reloading or replacing a direct iframe cannot inherit an earlier execution's notification activations. @@ -333,6 +379,12 @@ In-page toasts remain actionable when OS permission or service-worker notificati window opening remain browser-controlled. Native hosts need their own activation adapter; this browser change does not supply one. +### Background receiving activation + +Startup republication of unchanged, already-enabled watches in the current authorized receiver scope preserves its +revision, retained events, display receipts and transport synchronization state. A cold notification click therefore +survives product startup. Genuine watch changes still advance the revision and reject clicks from the previous policy. + ### Product chat Products that declare `includes.chat` in their `worker.