Trusted desktop client: a signed web app instead of server JavaScript
From mnema-talk v3.3.13, rendered on this site.
Status: implemented and shipped. The release tooling is in this repository and needs no server change. The hosts that verify and load the bundle are in talk-desktop: a Tauri host for Windows and macOS and an Electron client for Linux.
Why
Microphone, camera and screen payloads are sealed in the browser with MLS-derived keys, so an honest SFU cannot read them. SECURITY.md states the limit: an active or compromised server serves the web app, so it can serve a modified one that hands out the keys. In a browser that cannot be fixed, because the page is the server's page. A desktop client can fix it, because the client is something the user installed. Until now the desktop client did not use that freedom: it opened the instance's HTTPS origin in WebView2 and ran whatever JavaScript the instance sent.
The trusted desktop client ships the web app itself and verifies it. The instance supplies data, never code. Browser users are unchanged.
Decisions at a glance
| Question | Decision |
|---|---|
| Where does the app come from? | A signed bundle (a zip of web/dist plus a manifest). One is built into the installer; newer ones are downloaded from the GitHub release assets of this repository, verified, and cached. |
| How is it signed? | Ed25519 over manifest.json, which lists the SHA-256 and size of every file plus version, web_client_api, min_server_version and security_floor. Signed in the release workflow with a key kept as an Actions secret. |
| What does the desktop trust? | Public keys pinned in the desktop build (a list, for rotation). TLS and GitHub are transport only: a bundle is accepted because of its signature, never because of where it came from. |
| Rollback? | Monotonic semver version; a persisted high-water mark per web_client_api (the highest bundle version ever verified), below which no bundle is run, and a signed security_floor: bundles below the highest floor ever seen are refused. However the server answers. There is deliberately no "older server" override (see Rollback protection). |
| Server API newer or older than the bundles? | Exact web_client_api match, server.version >= min_server_version, bundle.version >= floor, bundle.version >= high-water mark of that contract. If none of the verified bundles qualifies the client checks for an update, and otherwise refuses to connect with an explanation. It never falls back to server JavaScript. |
| Can the instance's JavaScript still be loaded? | No. Not as an opt-in either: a malicious server could trigger the prompt on purpose and ask for consent in its own words. A developer-only build feature is not shipped in releases. |
| How does the local app reach the server? | A native proxy in the Tauri host behind a custom protocol, so the WebView still sees one origin and the web app's code (relative URLs, fetch, cookies in the browser model) works unchanged. The session cookie lives in the host, never in the page. WebSockets go through three IPC commands. |
| Server changes | None to the request path or the browser security model. The server already advertises version and web_client_api in /api/health. This repository adds the signing tooling, a contract file and tests that keep the two numbers in step. |
How the first desktop client loaded the app
Before the signed bundle, desktop_open_instance in the desktop host validated the address (HTTPS
origin only), read GET /api/health (status: ok, web_client_api: 1),
and opened a window on the instance origin. The page was an ordinary
browser page: the __Host- session cookie, the Origin check
(httpx.CSRF, allow-list from PUBLIC_URL / CORS_ALLOWED_ORIGINS), the
SPA CSP (script-src 'self') and the WebSocket at /api/ws all behave as in
a browser, which is why no server change was ever needed. The cost was the
trust model: script-src 'self' means the server's scripts.
The bundle
Contents and format
A bundle is one file, mnema-web-<version>.zip:
manifest.json what is signed
manifest.sig base64 Ed25519 signature over the exact bytes of manifest.json
app/<path> desktop files from web/dist (index.html, assets, wasm, fonts)
Dotfiles, and files below a dotted directory such as .well-known/, are rejected. api-docs.html and the apiDocs-* files Vite emits for it are not signed. The server embed still serves that page at /api/docs for a signed-in member.
manifest.json:
{
"schema": 1,
"name": "mnema-web",
"version": "0.8.0",
"web_client_api": 1,
"min_server_version": "0.7.16",
"security_floor": "0.0.0",
"commit": "<source revision>",
"key_id": "1069c76ff2e11272",
"files": [{ "path": "index.html", "sha256": "<hex>", "size": 1234 }]
}
versionis the release version, the same string baked into the web app (__APP_VERSION__) and the server binary.web_client_apiis the contract number the app speaks. The server advertises its own in/api/health;internal/serverandweb/desktop-compat.jsonare checked against each other by a test.min_server_versionis the oldest server release the app still works with. It lives inweb/desktop-compat.jsonand is bumped by hand when the web app starts to require something new from the server.security_flooris the oldest bundle version that is still acceptable. It lives inweb/desktop-compat.jsonand only ever rises. The release workflow raises it to the release's own version when the release contains a security fix, and every later release repeats that raise (see "Security floor" below); the baseline can also be raised by hand in that file. A bundle's floor never exceeds its own version.key_idis the first 8 bytes of SHA-256 over the raw public key. It only selects a pinned key; the signature check decides.- No timestamp: bundles are reproducible from the tag.
The signature covers the manifest bytes as published. The client verifies the signature before it parses the manifest, so a hostile manifest never reaches the parser unauthenticated.
The manifest and the trust statement (below) are read as serde_json reads
them with unknown fields denied: one JSON object in UTF-8 without a byte order
mark and with nothing after it, exactly the documented fields, spelled exactly
and all present (only max_version may be missing), each of its type (never
null; integers without sign, fraction or exponent), no key twice, no lone
surrogate in a string, and times not before 1970. A max_version key is read
like Rust's u32 parse (01 and +1 are API 1). webbundle verify and
webbundle trust verify read them the same way; trust verify also refuses
two keys naming the same API (such as 1 and 01), which the two clients
would resolve differently. The tool writes only the canonical spelling.
Signing
cmd/webbundle (package internal/webbundle, plain crypto/ed25519) has
four commands: build (directory + key to zip), verify (zip + public key),
keyid and trust (the signed trust statement, below). The release workflow runs it in a job after the image job:
it builds the web app with MNEMA_VERSION=<release>, signs with the Actions
secret WEB_BUNDLE_SIGNING_KEY, verifies the result against the public key
committed in this repository (web/desktop-signing.pub) and attaches
mnema-web-<version>.zip (plus manifest.json and manifest.sig for
auditing) to the GitHub release. Without the secret the job signs nothing
and succeeds (forks). Pull requests never see the secret.
The signed bytes are built inside the protected job. web-bundle runs in the
GitHub environment web-bundle-signing (limited to main) and builds
web/dist itself from the release tag, so no artifact from an unprivileged job
is ever signed. npm ci --ignore-scripts and npm run build each run in a
throwaway container (the digest-pinned node image of the Dockerfile's web
stage) with all capabilities dropped, no secret, no Docker socket, only a copy
of web/ mounted, and no network for the build. Code that runs during the
build, even from a dependency, can therefore change only that copy: it cannot
alter the job's environment, PATH, outputs or the signing step. The job
builds cmd/webbundle from the tag's own Go source in a step without the key
and hands the key to the single webbundle build step.
Residual risk: a poisoned npm dependency that is already in package-lock.json
still reaches the build output and would be signed, because the image build
uses the same lockfile (so comparing against the image proves nothing). The
lockfile pins every package with an integrity hash, Dependabot waits out a
cooldown before proposing updates, and the manifest hash is printed in the job
summary so the owner can rebuild on a second machine and compare. This job's
behaviour needs a real release run to be confirmed end to end; the container
steps were run locally against the same Dockerfile image.
Security floor
web/desktop-compat.json carries the baseline floor. Because only the three
release-please files may change in a release PR, the floor is raised at
signing time: the web-bundle job runs scripts/security-floor.sh on the
release tag. A release raises the floor to its own version when one of its
commits carries a Security-Floor: raise trailer (the last paragraph of the
commit message, so for a squash merge the end of the pull request
description), and every later release repeats the highest floor raised so far,
so a client that missed the raising release still learns the floor from the
next one. The script computes this from the git history and the release tags
alone (a raising commit belongs to the first release tag that contains it), so
a rebuild from the tag declares the same floor; it refuses a shallow clone,
and the pipeline has no way to lower the floor. The job passes
-security-floor <that version> to webbundle build. The flag only
raises, never lowers, the value from the compat file. The commit subject plays
no part: a fix(security) title alone neither raises the floor nor can a
lookalike scope such as docs(security-notes) raise it by accident. A subject
with the security scope but no trailer only prints a warning in the job log.
A line that starts with Security-Floor but is not exactly the trailer
Security-Floor: raise in the last paragraph (another paragraph such as
BREAKING CHANGE: follows it, or a near miss such as Security-Floor: raise.)
is refused instead of being dropped: the backend check of a pull request
fails when its title, its description (read as the squash commit: title, blank
line, description) or one of its commits has such a line, and the release job
fails when a commit of
the release has one (only the release's own commits, since the previous tag),
so that release gets no signed bundle until the next one carries the trailer
as the last paragraph. That includes a prose line wrapped so that it starts
with the key, and the marker quoted on its own line in a code block: mention
the marker inside a sentence, never at the start of a line.
So a vulnerability fix in anything the bundle ships (the web app: markdown,
media, auth, message rendering, crypto) must carry the trailer; the maintainer
checklist in AGENTS.md repeats this. A fix without the trailer leaves the
floor where the last raise put it, and old clients keep accepting older bundles
down to that floor until the next release that raises it.
The job builds the bundle tool in its own step without the key and passes
the key only to the single webbundle build step.
The private key is generated once with openssl genpkey -algorithm ed25519,
stored only as the environment secret and in the owner's backup directory
~/.mnema-signing/ (mode 700/600). Only the public key is committed.
Pinning and rotation
The desktop host embeds a list of (key_id, public key) pairs. A manifest is
accepted if one pinned key verifies it. These compiled-in keys are the default
until the client has fetched its first signed trust statement (next section).
A key can also be retired by a new desktop release that no longer pins it, but
that path is slow and an attacker holding the key can front-run it; the
trust statement is the remedy for a leaked key.
Key revocation: the offline root key and the trust statement
A leaked CI signing key must be revocable without shipping a new client, so a
third key exists that never touches CI: the offline root key (Ed25519).
Its public half is committed as desktop-trust/root.pub and pinned in the
desktop client. It signs one small statement:
desktop-trust/trust.json:schema,serial(grows with every statement),issued_at,expires_at(UTC, at most 400 days afterissued_at; the CLI default is 180 days),bundle_keys(allowed web bundle public keys, raw Ed25519 in hex),revoked_bundle_keys(key ids),updater_keys(allowed Tauri updater public keys, in the text form oftauri.conf.json) andrevoked_updater_keys(minisign key ids, hex in file order) andmax_version(optional caps, see below).desktop-trust/trust.json.sig: base64 Ed25519 signature over the exact bytes oftrust.json.
Both files are served from
https://raw.githubusercontent.com/mnema-xyz/talk/main/desktop-trust/.
The transport is untrusted; only the signature counts. No release is needed:
merging a new statement to main publishes it.
How the client uses it (the desktop repository implements the same format in Rust):
- It fetches the statement at start and at every six-hourly check, verifies the signature with the pinned root key before parsing anything, and keeps the last good statement on disk.
- Anti-rollback. The highest serial ever accepted is persisted. A statement with a lower serial is refused; an equal serial changes nothing.
- Authoritative. Once a client holds a statement, it accepts web bundles
only from keys listed in
bundle_keysand not inrevoked_bundle_keys. The compiled-in keys no longer count. Bundles already held (built-in or cached) are checked again; those signed by a withdrawn key are dropped (and their cache files removed). - Rollback marks are per key. The client records which key raised each rollback mark (highest bundle version per contract, and the security floor). The marks in force are the highest ones raised by keys that are still trusted. Revoking a key therefore clears the marks a forged high-version bundle raised, but never drops below what a still-trusted key reached or declared. Until a bundle from an allowed key at or above the mark exists, an older one is refused with a clear message.
- Explicit caps. A statement may carry
max_version(for example{"1": "0.9.0"}, web client API number to version; sign with-max-version 1=0.9.0). When a client first takes that statement, it lowers its recorded marks for that API to at most the cap and drops held bundles above it, even if no trusted bundle exists yet. Caps are not carried over to later statements and a cap above the legitimate versions does nothing, so use it only to clear a forged mark. - Freshness (freeze protection). An attacker who blocks the fetch must not
keep a stale statement in force. A statement past
expires_atis never accepted, and while the one in force has expired, or this round's fetch failed, the client installs no new bundle and no updater package. It keeps running the already verified installed bundle, and an expired statement still applies its revocations. Re-sign before expiry (below). - Fail closed, stay usable. If a statement cannot be fetched or does not verify, the last good one stays in force (or the compiled-in keys, if there never was one). If the only bundle left was signed by a revoked key, the client says so and asks for an update instead of running it.
- Updater. The Tauri updater verifies installers with one public key from
tauri.conf.json. The client additionally refuses any update whose signature names a revoked updater key id, and, for key rotation, uses the matching public key fromupdater_keyswhen the signature names one that is not the built-in key. Limit: the updater is only as trustworthy as the signed installer it checks; revocation cannot undo an installer that a client has already run. - The statement is cumulative for revocations:
webbundle trust sign -prevcarries earlier revocations forward, and a key that was revoked cannot be allowed again.
Root key handling: the private key lives only at
~/.mnema-signing/offline-root.key (directory mode 700, file mode 600). It is
never a GitHub secret and never in CI. Keep a copy offline (USB stick or
password manager); losing it means a new desktop release is the only way to
change the root key.
Renewing the statement (every 3 months)
A statement is valid for 180 days. Renew it well before then, on the machine that holds the root key, with one command, then merge the result:
go run ./cmd/webbundle trust sign -key-file ~/.mnema-signing/offline-root.key \
-out desktop-trust -prev desktop-trust/trust.json -renew
-renew keeps the allowed keys and all revocations and raises the serial.
The previous statement must carry a valid signature (trust.json.sig, or
-prev-sig) from this root key; the tool refuses an unsigned or altered file, so
nobody can get a key root-signed by editing desktop-trust/ in a pull request.
Before signing it prints the full result, allowed and revoked keys with short ids
and +/- against the previous statement, and asks for confirmation. Read it:
every allowed key must be one you recognise.
go run ./cmd/webbundle trust verify prints the expiry
(-min-valid-days N also fails when fewer than N days remain). A client that
cannot get a fresh statement keeps working but stops installing updates. The
weekly workflow trust-expiry.yml runs that check with 60 days and fails
early enough to renew in time; the runbook is in
operations.md.
Runbook: a CI signing key leaked
Assume the leaked key is the web bundle key (web-bundle-signing). The
updater key works the same with -updater-key and -revoke-updater-key.
- Generate a new key pair locally (never in CI):
openssl genpkey -algorithm ED25519 -out new.keyandopenssl pkey -in new.key -pubout -out new.pub. - Replace the
WEB_BUNDLE_SIGNING_KEYsecret of theweb-bundle-signingenvironment withnew.key, commitnew.pubasweb/desktop-signing.puband deletenew.key. Rotate the environment's access if the leak was through GitHub. - Issue the statement on the machine that holds the offline root key:
go run ./cmd/webbundle trust sign -key-file ~/.mnema-signing/offline-root.key -out desktop-trust -prev desktop-trust/trust.json -bundle-key web/desktop-signing.pub -revoke-bundle-key $(go run ./cmd/webbundle keyid -pub OLD.pub)(use the old key's id;OLD.pubis the previousdesktop-signing.pub). Check it withgo run ./cmd/webbundle trust verify. - Open a pull request with
desktop-trust/andweb/desktop-signing.puband merge it. Clients pick the statement up at their next start or six-hourly check and stop accepting the old key at once. - Cut a release so a bundle signed with the new key exists
(raise
security_floorinweb/desktop-compat.jsonif the old key's bundles were vulnerable). Clients whose only bundle was signed by the revoked key show a message and fetch the new bundle on that check.
How the desktop verifies, caches and selects
Sources
- Built-in.
mnema-web-<version>.zipof a release is compiled into the desktop executable. It is verified with the same code path at every start, so a build with a broken or unsigned bundle fails visibly. - Cache.
<app data>/web-bundles/mnema-web-<version>.zip, at most three versions. Every cached bundle is fully re-verified on every load (hash of every file against the signed manifest, no extra or missing entries, bounded sizes) and then served from memory. There is no state in which unverified bytes are served: modifying one byte of a cached file makes that bundle unusable and the client falls back to the next verified one. - Update. The host asks
api.github.com/repos/mnema-xyz/talk/releases/latest(at most every six hours, and immediately when no bundle fits the server) and downloadsmnema-web-<version>.zipwhen its version is newer than everything held. Redirects to GitHub's asset hosts are followed, HTTPS only, with a size cap. The result is verified like any other bundle before it is cached.MNEMA_DESKTOP_NO_UPDATE_CHECK=1turns the request off. The request reveals the user's IP address to GitHub and nothing else.
Zip handling
Entries must be exactly manifest.json, manifest.sig and app/<path> for
every manifest entry; no duplicates, no extras, no .., absolute paths,
backslashes or control characters; at most 4000 entries, 64 MiB per file and
256 MiB in total, counted while decompressing (a zip bomb stops at the
limit).
Rollback protection
The host keeps state.json next to the cache:
{ "floors", "marks", "last_check" }. Both numbers are recorded per signing
key (by key id), so a key that is revoked later takes the marks it raised
with it:
floorsmaps each key id to the highestsecurity_floorthat key ever declared in a verified manifest.marksmaps eachweb_client_apito, per key id, the highest bundle version that key ever signed and this machine verified (built-in, cached or downloaded).
The floor and the high-water mark in force are derived from these: the highest
value of any key that is still trusted. security_floor and high_water in
the file are the older, signer-less format; they are read once as the unknown
signer (always counted) and no longer written. The marks are rebuilt from the
held bundles if the file is lost. They only rise, except in two cases that
exist to undo a forged mark: a key that a trust statement revokes stops
counting (the marks in force fall back to what still-trusted keys reached or
declared), and a statement with max_version lowers the recorded marks and
floors to at most the cap (see Key revocation).
- A bundle is refused when
version < security_floor, where the floor is the maximum of everysecurity_floordeclared by a still-trusted key's verified manifests. - Strict high-water rule. A bundle is never selected when its version is
below the high-water mark of its contract, even if it is validly signed,
above the floor and the only one the server's version fits. The rule is "never
run a bundle older than one that was already verified here". Marks are kept
per
web_client_api, because bundles of different contracts cannot replace one another; a client that talks to servers of two generations keeps both. - An update is installed only if its version is greater than the highest
verified version held. Old but validly signed bundles that an attacker
replays cannot replace newer ones, and
latestmetadata that moves backwards is ignored. - A server cannot influence these numbers. What a server can do is claim an
old
versionin/api/healthso the client would pick an older bundle. The floor alone did not stop that, because the floor (currently only raised for security fixes) can lag far behind. The high-water mark does: a server that claims an old version now gets the refusal "needs X or newer", not an old bundle.
Trade-off against older servers: once the client has verified a bundle with
min_server_version N, a server older than N is refused even if an older
signed bundle that supports it is still in the cache. Older servers are
exactly where known-vulnerable bundles are most useful to an attacker, and the
alternatives (a per-instance opt-out, or a "compatibility mode" that runs the
older bundle) make the attacker's claim a user prompt, which the server can
word itself. The remedy is to update the server; the message names the version
needed. A reinstall of the desktop client does not lower the marks either as long as its
application data directory survives; a fresh data directory starts from the
built-in bundle of that installer, which is the newest the installer knows.
If the newest verified bundle is deleted from the cache (and a newer one is not
downloaded), the client refuses with "newest verified app no longer
available" instead of running an older one, and an update restores it.
State is not signed. An attacker who can write the user's application data can replace the executable as well; that is outside this model.
Compatibility: bundle versus server
At connect time the host reads version and web_client_api from
/api/health (bounded, no redirects, system TLS) and applies:
| Situation | Behaviour |
|---|---|
A verified bundle has web_client_api == server and server.version >= min_server_version and bundle.version >= floor and bundle.version >= high-water mark | Use the highest such version. |
Server version is not a release (dev) | Only web_client_api must match. (For local development.) |
Server web_client_api is newer than every bundle | Check for an update now. If a matching bundle arrives, use it; else stop with: "This server needs a newer Mnema app than this client has. Update the desktop client." |
Server is older than every usable bundle (below every min_server_version, or older bundles are gone or below the floor) | Stop with: "This server runs vX; this desktop client needs at least vY. Ask the administrator to update." |
/api/health has no web_client_api | Stop ("not compatible"). |
The chosen bundle is pinned for the lifetime of the instance window. A newer bundle found later takes effect on the next start of that window; the app shows "restart to use verified app vX" instead of reloading.
Server JavaScript: not at all
Loading the instance's own JavaScript is not offered, neither silently nor
as an opt-in. Reasons: the dialog could be triggered by the very server the
feature protects against (it controls web_client_api and version); a user
who is told "the server's app is different, continue?" has no way to judge
it; and the old mode would keep the original hole one click away. The
legacy path is removed from the host rather than hidden. Whoever needs to
run an unreleased web app signs a bundle with a key of their own and builds a
host that pins that key (MNEMA_BUNDLE_ZIP embeds it); the pinned list is in
the source, not configurable at run time.
One address exception exists: an instance on the same machine may be entered
as http://localhost, http://127.0.0.1 or http://[::1] (a development
stack). Anything else must be HTTPS with normal system certificate checks.
Origin and authentication
Options
| Option | What it takes | Verdict |
|---|---|---|
A. Custom origin + CORS + bearer token. The app runs at tauri://localhost and calls https://instance/api cross-origin. | Server: allow the desktop origin in CORS, accept a bearer token (new auth path), change WebSocket auth (no cookie across sites; SameSite=Lax blocks it; the Origin check rejects it), change the CSP connect-src. Web: base-URL plumbing for every fetch, <img>, <video>, attachment link and WebSocket, token storage in the page. | Not simple, and it weakens the browser model: new CORS allow-list entry, a second auth path, a long-lived token in JavaScript land. |
| B. A native session API with its own web transport. (Existed as unmounted research code; removed from this repository.) | Mount routes, finish the broker, rewrite the web transport for the whole REST surface. | Large, and aimed at the native-crypto research mode. Not needed here. |
| C. Proxy inside the Tauri host. The WebView loads the app from a custom protocol; the host forwards requests to the instance. | No server change. Host: URL handler, cookie jar, response filter, WebSocket bridge. Web: one socket factory. | Chosen. |
The proxy
The host registers the custom protocol mnema and opens the instance window
at mnema://localhost/ (WebView2 on Windows shows it as
https://mnema.localhost/). Everything the page requests arrives at the
host:
Static files: path in the verified bundle, else (for non-
assets/paths without a file)index.html, exactly asweb/web.godoes. Responses carry the SPA CSP ofinternal/httpx(script-src 'self' 'wasm-unsafe-eval',connect-src 'self' ipc: ...) and the same hardening headers (the desktop shells apply the strict web CSPstyle-src 'self'; style-src-attr 'none'only for web bundles >= 1.1.0; older bundles keep the old policy)./api/...: forwarded to the instance origin with a fixedreqwestclient (system TLS, no redirects, no proxy, timeouts, and bodies buffered in memory up to 128 MiB: the webview protocol cannot stream, so a larger answer is refused up front from its declared length; audio and video arrive inRangepieces). Only/api/paths, no dot segments, are forwarded. The host setsOriginto the instance origin itself, so the server's CSRF check sees exactly what a browser on that instance would send. It drops anyOrigin,Referer,CookieandHostthe page supplied and forwards a short list (Content-Type,Accept,Accept-Language,Range,If-None-Match,If-Modified-Since,X-Request-Id).Cookies: the host keeps its own cookie jar for the instance (Set-Cookie is parsed,
Secure/expiry honoured,Set-Cookieremoved from what the page receives). The session token never enters the page, so even a cross-site-scripting bug in the web app cannot read or exfiltrate it. The jar is persisted so the user stays signed in: in the macOS Keychain or Windows Credential Manager (servicemnema-desktop-session, one entry per instance). Only where no keychain exists, or it refuses the write, the host falls back to a mode-600 filesessions/<hash>.jsonin the application data directory; a file written by an earlier version moves into the keychain at the next start and is deleted. A program running as the same user can still ask the keychain; what changes is that copies of the profile, backups and file listings no longer carry a live session.WebSocket: custom protocols cannot carry upgrades, so the page uses a
TrustedSocketclass with the browserWebSocketsurface (onopen,onmessage,onclose,send,close) over three IPC commands:desktop_ws_open,desktop_ws_send,desktop_ws_close, plus a Tauri channel for events. The host openswss://instance/api/wswith the jar's cookie and the instanceOrigin; frames are text, bounded in size and count. The chat store's existing reconnect logic is untouched. The path is/api/ws, with the one query the server understands,?dm=1(conversation events, 1.1), when the host announces the capabilityws_queryin the instance window's identity; a host without it only gets the plain path, so a 1.1 bundle never asks an older client for a socket it would refuse.Responses are data, not code. Everything from the server is filtered before the page sees it: only an allow-list of headers is passed on,
Content-Typeof anything that could render as a document in the app origin (HTML, SVG, XML, scripts, unknown) is replaced byapplication/octet-streamwithContent-Disposition: attachment, and every proxied response carriesContent-Security-Policy: sandbox; default-src 'none'andX-Content-Type-Options: nosniff. Without this, a hostile server could answer an attachment URL with HTML and run it in the app origin, with access to IndexedDB (the MLS state) and IPC. The same rule protects the child window used for attachments.Navigation is limited to the app origin; HTTPS links elsewhere go to the system browser after a confirmation, as today. The instance window may also navigate to same-origin
/api/URLs (download and attachment links), and a link opened in a new window goes to the attachment child window. Both are answered by the proxy, so what arrives is forced into a sandboxed download or inline-safe media, never a document of the app origin. The attachment child window and the gaming surfaces use the same protocol and the same bundle.OS notifications and the app badge (host capability
notify). The identity of the instance window carriescapabilities: ["notify"]; the selector, gaming surfaces and the attachment window announce none, and a client from before this feature announces no list at all, in which case the app falls back to the browser's Notification and Badging APIs. The commands aredesktop_notify_open(a channel that reports which toast was clicked, as{channel_id, message_id}),desktop_notify(title,body,channelId,messageId),desktop_notify_permissionanddesktop_notify_request_permission(both answergranted,denied,defaultorunsupported) anddesktop_set_badge(count). They are allowed only in the instance window, never on the selector or a gaming surface. The host treats everything as untrusted text: control characters are flattened, title and body are truncated, ids must be plain identifiers, and toasts are rate limited, so a hostile server cannot show markup or spam the desktop. The OS owns the permission and the host reports it: on macOS the system asks once (UserNotifications), when the page callsdesktop_notify_request_permissionor at the first toast, anddefaultmeans it has not been asked yet; Windows and Linux never ask and answergranted(a toast the person turned off in the system is dropped without an error). A page that gets an unknown-command error from these two commands (a client from before them) keeps treating the permission asgranted. Clicking a toast is reported by the platform itself (the toast's activation on Windows, the notification delegate on macOS, theclickevent on Linux) and also brings the window forward. Windows shows a dot as the taskbar overlay, macOS and Linux the count on the dock or launcher icon. This needs noweb_client_apibump: the web app detects the capability.Incoming calls in toasts (host capability
notify_call, optional, on top ofnotify). A Talk started in a direct message rings the other members (see Talks); the page then shows an incoming call card of its own and, only while the window is hidden or without focus, a toast throughdesktop_notifywith the title "{name} is calling you" and the body "Direct message · Click to join" (German: "{name} ruft dich an", "Direktnachricht · Klicken zum Beitreten"). A host that announcesnotify_callin the instance window'scapabilitiesadditionally getskind: "call"in the arguments ofdesktop_notifyand the commanddesktop_notify_close(channelId). Forkind: "call"the host may keep the toast on screen until it is used (Windows: the incoming-call toast scenario; macOS: a time-sensitive notification; Linux: urgency critical and a resident notification), offer a Join and a Dismiss button next to the toast itself, and report the button in the click event as{channel_id, message_id, action: "join"}(actionis absent for the toast itself and for Dismiss, which the host handles without telling the page). A click of any kind still brings the window forward. The page opens the conversation at the invitation for the toast, and joins the Talk as well foraction: "join".desktop_notify_closewithdraws the toast of that channel when the call stopped ringing (answered on another device, cancelled, timed out). The host treats the arguments like the other notification arguments (flattened, truncated, plain identifiers, rate limited). A host without the capability keeps showing the call as the ordinary toast, and a click on it already opens the conversation. Noweb_client_apibump.Unread report (host capability
unread, 1.1; the multi-instance client). One window of the client now shows one server out of several, and the client lists them on a rail with an unread dot and a mention count each. A host that announcesunreadin the instance window'scapabilitiesgetsdesktop_report_unread(unread: channels with unread messages that may notify,mentions: unread mentions; both whole numbers, 0 to 999) instead ofdesktop_set_badge, and sums the counts over its instances for the taskbar or dock badge.Platform.reportUnread/supportsUnreadReport(web/src/shared/lib/platform.ts) do the feature detection, so a client without the capability keeps gettingdesktop_set_badge, and a browser gets neither. Noweb_client_apibump. Allowed only in the instance window, like the other notification commands.Busy report (host capability
busy; the multi-instance client). The client closes the page of a server that stayed hidden for a while to save memory (110 to 260 MB per page), and asks first whether the page is busy. A host that announcesbusyin the instance window'scapabilitiesgetsdesktop_report_busy(all booleans, each true only while closing the page would lose something:draft, text typed and not written yet, or a draft the browser's storage refused, while stored drafts come back after a reload;upload, a file in a composer's tray, waiting, uploading, or uploaded and not sent;talk, the member is connected to a Talk) right after the page started and on every change.Platform.reportBusy/supportsBusyReportdo the feature detection, so a client without the capability gets nothing. Noweb_client_apibump. Allowed only in the instance window.Mark all as read (from the rail's menu, desktop 1.3). The host cannot reach the chat store, so it runs
window.dispatchEvent(new CustomEvent('mnema-desktop:mark-all-read'))in the page of that server. The instance window (role: 'instance'only) marks every channel and conversation read through the same path as the sidebar (useDesktopMarkRead, started byuseAppBadge); the new counts reach the rail by the unread report above, which fires whenever the read states change. Nothing is sent back.
Why this keeps the browser model intact
- CSRF: unchanged. The Origin the server sees is the instance's own, set by trusted host code.
- Cookies: unchanged flags; the host is a stricter cookie holder than a browser (page cannot read it).
- CSP: unchanged for browsers; the desktop app gets an equivalent policy
from the host (the desktop shells apply the strict web CSP
style-src 'self'; style-src-attr 'none'only for web bundles >= 1.1.0; older bundles keep the old policy). - Rate limits and lockouts: unchanged; requests come from the user's own address and are counted as theirs.
- No allow-list entry such as
tauri://localhostis added toCORS_ALLOWED_ORIGINS.
Web app changes
web/src/shared/lib/native/trustedDesktop.ts reads the identity the host injects before
any page script (window.__MNEMA_TRUSTED_APP__, defined by an
initialization script, frozen): version, source (builtin or cache),
web_client_api, key_id, server_version. The app uses it to pick
TrustedSocket, to hide the browser's "reload for the new version" banner
(replaced by the restart hint), to show Verified app vX in the account
menu and to enable the gaming bridge on the local origin. In a browser none
of this exists and nothing changes.
Several servers at once
Since the 1.1 client one window shows several servers: a rail on the left (a page of the host, independent of every bundle and server) lists them with an unread dot and a mention count each, and the page of one server sits next to it. One account per server, no federation; there is no limit on the number of servers (Ctrl+1 to Ctrl+8 reach the first eight and Ctrl+9 the last, Cmd on macOS, and Ctrl/Cmd+K opens a quick switcher), reordered by dragging or Alt+arrow, grouped in folders, removed from the tile's menu. Servers stay fully separate:
- A page is tied to its server by its webview label (
i-<id>, the id is the first 8 bytes of SHA-256 over the instance address, hex). The protocol handler and every host command look the server up from the label of the calling webview and never from an argument, so a page cannot name another server's session, socket, counters or toasts. The capabilities are by webview: pages (i-*) get the socket, notification, unread and gaming-bridge commands, only the rail getsrail_*(switch, add, move, remove, reconnect) and only the page for adding a server getsdesktop_open_instance. - Session: one cookie jar per server, stored in the keychain under the id
of that server (one entry per instance, as before). One per origin: the
/api/healthdocument carries no community id, so none is part of the key. - Browser storage is separate per server, because the pages share the
local origin and would otherwise share IndexedDB (the MLS state) and
localStorage: a WebView2 user-data folder per server on Windows, aWKWebsiteDataStoreper server on macOS 14 and newer, a session partition (persist:inst-<id>) per server in the Electron client. Where a platform cannot separate the storage (macOS before 14) the client runs one server rather than share it. The host's own pages use a storage of their own, too. - Sockets:
desktop_ws_*act on the calling server's relay only, with its own budget. The relay opens/api/wsand, when the page asks,/api/ws?dm=1(conversation events); the page announces nothing else the host would accept. - Bundles: the verified bundle is chosen per server from its own
/api/health, so a 1.0.x and a 1.1 server can run side by side, each with the web app that fits it and the style policy of that bundle version. The high-water mark stays one perweb_client_api. A server that is too old or too new keeps its place and shows the refusal in its own tab only; "Reconnect" in its menu asks again. - Counts and the badge: pages report
unreadandmentions; the badge of the taskbar or dock is the sum of the mentions. A toast names its server once there are several, and using it brings that server forward and reaches only its page. - Gaming (Windows overlay, shortcuts, sidepeek) belongs to one server at a time: the one that owns the Talk the person is in. Another server's state is ignored while that Talk is live, and commands go back to that server's page with its own token.
- Background servers are hidden, not stopped: their relay socket, counters and calls keep running, the engine only stops painting them.
- Removing a server wipes its keychain entry (and the fallback file), its
browser storage (the engine's storage is cleared, then the profile folder or
data store is deleted, with a sweep at the next start for what a cut-short
removal leaves), its sockets, toasts and gaming token, and its entry in the
list. The list (
instances.json) holds addresses only. - Updating from the single-server client: that client kept every server in one shared browser storage and recorded none of them (only trust state, bundles and per-origin sessions), so the storage belongs to no one server and its owner cannot be proven. It is never handed to a server: it is wiped once, on the first start of the new version, and every server starts with a storage of its own. Stored sessions stay per exact origin as a sign-in convenience. The cost is one new sign-in and a new device key for the end-to-end media; messages live on the server and are unaffected.
A server that ended the session (the kicked event of /kick, a password
change, a sign-out elsewhere) leaves a stale cookie in the jar, as a browser
does: requests are answered 401 until the person signs in again, which replaces
the cookie. Nothing reconnects by itself with a refused session.
Updating the client itself
The signed web bundle covers the web app. The program around it (the shell) is replaced by its own, separate mechanism, so that users never have to download an installer by hand after the first time.
- Feed and key. On Windows the installer is a per-user NSIS package and the
portable copy a signed ZIP; macOS has a signed
.app.tar.gzand Linux signed AppImages. All are built by the talk-desktop release workflow on avX.Y.Ztag. Installed clients readhttps://github.com/mnema-xyz/talk-desktop/releases/latest/download/latest.jsonat every start and every six hours (the interval of the bundle check). The feed is not trusted: it only names an installer and a minisign signature. The updater key (Ed25519, minisign format; the official Tauri updater) is a different key from the bundle key and its public half is pinned intauri.conf.jsonof the client. The Electron client for Linux applies the same rules in TypeScript; a.debinstallation is owned by the package manager, so the client only announces a newer version. - What is verified. The installer runs only if its signature verifies
against the pinned key, the version recorded inside the signature equals the
version the feed announces (
requireSignedVersion: an old signed installer cannot be passed off under a new version number), the version is strictly newer than the installed one (no downgrade), and the download URL is HTTPS ongithub.com. Where the bytes came from decides nothing. "On next start" keeps the verified installer on disk and verifies it again against a freshly fetched feed before it runs; an installer that changed on disk, or that a newer release replaced, is deleted. - Install. Per user (
currentUser), passive mode: no administrator prompt, the app restarts afterwards. This does not depend on a platform signature. - User control. Update now, On next start, Skip this version (a newer
version is offered again), retry after a failure.
MNEMA_DESKTOP_NO_UPDATE_CHECK=1turns the check off. - Key custody. The private key is a secret of the protected
desktop-updater-signingenvironment of the desktop repository (usable by tagsv*only) and in the owner's offline backup. It is separate from the bundle key and from every server. - Rotation and revocation. Clients trust exactly the key in their own config. To rotate, publish a release that carries the new public key but is signed with the old key, and only then switch to the new key. A client that never received that release cannot install releases of the new key and needs a manual install. If the updater key is compromised, a trust statement signed by the offline root key revokes it and lists its replacement (see "Key revocation"); clients refuse installers signed by a revoked key and accept the replacement key. A bad release is replaced by a higher version, never by lowering.
- Residual risk. Whoever holds the updater key, or both the GitHub account and a way around the protected environment, can ship malicious code to every installed client. A network attacker can withhold updates (freeze) but not forge them. The first installer download still relies on how the user got it (see the installer gap below).
Threat model for desktop users
| Notes | Active or compromised server |
|---|---|
| No longer possible | Injecting or replacing JavaScript, WebAssembly, CSS or HTML of the app. Reading the session cookie from the page. Turning an attachment or API answer into code in the app origin. Downgrading to an older, vulnerable app: below the security_floor, or below the highest bundle this client already verified for the server's contract. Serving a bundle with another key. |
| Still possible (unchanged) | Seeing metadata (who talks when, frame sizes, layers, quality choices, connection timing). Reading text messages and attachments. Asserting group membership and relaying MLS handshakes: adding a member, swapping a leaf, steering a newcomer into its own group, forcing group restarts, withholding heartbeats (see SECURITY.md). Denial of service: dropping messages, refusing connections, lying in /api/health so that the client refuses to connect. Sending hostile data (messages, link previews, ICE servers) that the unchanged app code must handle. |
| Still possible for the supply chain | Whoever holds the signing key, or the GitHub account that publishes desktop installers, can ship a malicious app. The key is separate from the server; compromise of a community server does not give it. The installer itself is not Authenticode-signed (see "Known gap" below), so how the user obtained it still matters. |
| Freeze | A network attacker can withhold updates; the client keeps what it has. The security_floor and the high-water marks only move when a newer bundle is seen. |
Browser users remain exactly as in SECURITY.md: the server serves the code.
Known gap: the installers have no platform signature
The signed bundle protects the web app, not the program around it. The Windows
installer has no Authenticode signature and the macOS app is ad-hoc signed, not
notarized, because the project does not buy certificates. Consequences:
SmartScreen and Gatekeeper warn on first run, and nothing ties the program to
the publisher on the user's machine. Later updates are verified by the pinned
minisign key instead.
The desktop release carries a SHA256SUMS file next to the installers, which is only
protection against a corrupted download: it is published by the same account in
the same release, so whoever can replace the ZIP can replace the checksums.
It does not prove who built the file. Anyone who needs more than that builds the client from source. The bundle key pinned in the
executable is what makes the rest of the client trustworthy after install; the
executable itself is trusted as far as its download was.
Verification plan
internal/webbundle: build, sign, verify, tamper (changed file, extra file, missing file, bad signature, wrong key, bad paths, size limits) at the repository coverage level.- CI: build a bundle from
web/distwith an ephemeral key, verify it with the tool, and check thatweb/desktop-compat.jsonagrees with the server. - Desktop: Rust unit tests for manifest and zip parsing, signature, floor, selection against server health, response filter, cookie jar and header allow-lists; UI tests; tamper test on a cached bundle; a local run against a throwaway stack. Anything that needs WebView2 (custom protocol mapping on Windows, media permission prompts, the gaming overlays) is listed as Windows-only in the desktop repository's status page.
Rules acceptance
Community rules (/api/onboarding, see roles-and-permissions.md)
and custom emoji (/api/emoji, /api/admin/emoji) reach the shipped desktop
clients through the trusted proxy like any other /api call, so members accept
rules and use emoji in the web app as usual.