Skip to content

Harden the desktop app against its threat model and document what is implemented - #426

Open
cxxxxxn (cxxxxxn) wants to merge 22 commits into
mainfrom
security/desktop-threat-model-hardening
Open

cxxxxxn (cxxxxxn) wants to merge 22 commits into
mainfrom
security/desktop-threat-model-hardening

Conversation

@cxxxxxn

@cxxxxxn cxxxxxn (cxxxxxn) commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Why

A security reviewer asked whether every mitigation in docs/desktop-threat-model-attachment.md is implemented. It was not: the document listed planned remediation next to existing controls. This PR implements the gaps we chose to close and rewrites the document so that every control it claims names where it lives in the code.

Scope is the installed desktop app in its default mode (the app starts its own local Server). --server remote mode is out of scope and unchanged.

What changes

Desktop

  • Launch token. Loopback is reachable by every program and user on the machine, and a caller there was the owner. The app now starts its Server with a random per-launch token and adds it to requests from its own pages; the Server answers 401 to anything else. Agents keep reaching back with the machine credential.
  • Permissions and downloads are denied by default in local mode. The app's own pages keep clipboard, audio recording, fullscreen and downloads of their own files; a framed page keeps fullscreen only.
  • The Server's files stay in the app. The system browser holds no token, so the app's pages open a stored file over IPC: an image is shown in an app window, anything else is saved. A link to such a file opened in a new window does nothing, since a framed page can open one too.
  • A framed document on the app's own origin never gets that origin, whether a Web node names a stored file by key or by absolute URL.
  • Privileged IPC (window, diagnostics, folder picker, updater, menu) answers only a main frame of an app window on the app origin, as the Tab and local Agent channels already did.
  • Windows updates are accepted only when signed by Microsoft Corporation. The release pipeline fails if the ESRP signer is anyone else.

Server

  • Content fetches stay on the public network on desktop (HUABU_PUBLIC_NETWORK_ONLY=1): web pages, files imported by URL, inlined images and remote PDFs refuse loopback, private, link-local and metadata addresses, redirects included. Model endpoints are not affected. Where HTTP(S)_PROXY is configured each redirect hop is sent the way it actually leaves: guarded at connection time when NO_PROXY or the scheme exempts it, checked beforehand when the proxy carries it.
  • Every stored document renders in an opaque origin, in local mode as under per-Space access, so a framed remote page that redirects to a stored HTML file cannot run as the application.
  • Fetched bodies stop at a size limit (20 MB page, 50 MB file) instead of being buffered whole.
  • Fix: since undici 8 (build(deps): bump undici from 7.30.1 to 8.12.2 #346) the existing public-network guard failed every request, whatever its address, so a Bubble member could fetch no web page at all. The tests only asserted that a fetch failed; they now assert the guard's own refusal. This commit (fix(server): let the public-network guard reach public addresses again) is worth cherry-picking on its own.

Agents

  • Newly discovered Agents ask before each tool call. A discovered Agent whose CLI supports it used to be created with auto-approval on. It is now off: the conversation shows each request with Allow once, Always allow and Deny. The user turns auto-approval on in Settings, or for one conversation with the Agent's approval selector in the chat input. Profiles that already exist keep their setting.

Docs

  • docs/desktop-threat-model-attachment.md: implemented controls with code paths, and a separate list of what is not implemented.
  • docs/architecture/: deployment security, desktop startup and desktop auto-update describe the new behaviour.

Behaviour changes to expect

  • curl or scripts calling the desktop app's local API without the token get 401.
  • An Agent pointing a node at a localhost or intranet URL no longer has it downloaded by the Server; the node keeps the URL.
  • Framed web pages cannot request device permissions or start downloads.
  • On a new install, an external Agent such as Copilot asks before every command until the user turns auto-approval on. Creating one note took three confirmations.

Verification

  • Unit tests: desktop (214), server identity / security / preprocessing / canvas import (506), release script (14). pnpm typecheck, pnpm format, pnpm lint:fix clean.

  • The launch token's attribution, probed in a real Electron 43.8.1: 21 request kinds from the app (navigation, fetch, workers of three kinds, event stream, framed app documents, requests as the window closes, the main process) and from a framed page on another loopback port (fetch, blob document, about:blank frame, workers of three kinds). Every app request carried the token and no foreign one did.

  • End to end against the real app (unpackaged, macOS, isolated data directory), 33 checks, rerun after each round of review fixes: app admitted and every other local caller refused on all surfaces; Space Tabs in their own session, live streams, image display, own-file download; foreign download cancelled; framed page has no IPC bridge, no permissions, cannot read or write the API; Server never fetched a loopback URL an Agent wrote, and did fetch a public one.

  • A real GitHub Copilot conversation in that app: streamed reply, three reachback calls admitted, the note it created appeared on the open Canvas with its change-review card.

  • Auto-approval, with real Copilot conversations: a fresh install creates every discovered Agent with it off and asks before the first command; with it off, creating a note asked three times and finished once allowed; turning it on in Settings, and separately with the chat-input selector, each let the next turn finish without asking.

Not verified

  • Windows, a packaged build, and development mode behind the Vite proxy.
  • A real proxy: the proxy path is tested with a stubbed fetch, not against a proxy server.
  • The pipeline's publisher check: it runs only in the Azure Windows job. A wrong publisher name fails that release rather than stranding users.
  • The built-in Agent (needs stored model credentials) and microphone recording.
  • What "Always allow" on a confirmation covers, and Agents other than Copilot with auto-approval off.

Before the first release with this change

.github/workflows/release.yml still publishes an unsigned Windows installer on a tag push. Installed apps that carry the publisher check would refuse an update from it. It is to be disabled; the official path is azure-pipelines.yml.

Follow-ups

Not in this PR

Listed as open in the threat model: Agent sandboxing and environment allowlist, per-Space reachback tokens, marking external content as untrusted, live previews and remote images loading in the renderer, unsigned binaries inside the Windows installer, and immutability of published release assets (the upload step is outside this repository).

🤖 Generated with Claude Code

cxxxxxn (cxxxxxn) and others added 11 commits November 19, 2026 10:42
Electron grants every permission request and saves every download when a
session has no handler. The application's own top-level pages keep the
clipboard, audio recording, fullscreen and their own file downloads; a framed
page keeps fullscreen only.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ages

The window, diagnostics, folder-picker, updater and menu channels now apply
the check the Tab and local Agent channels already had: the sender must be a
main frame of a Huabu-owned renderer on the application origin.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Since undici 8 (#346) the guarded dispatcher rejected the handlers of Node's
built-in fetch, so every guarded request failed, whatever its address: a
member could fetch no web page at all. Wrap it for that protocol.

The tests only asserted that a fetch into the Server network failed, which
this regression satisfied. They now assert the guard's own refusal.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…twork

HUABU_PUBLIC_NETWORK_ONLY=1, which the desktop app now sets, applies the
existing public-address guard to the owner's content fetches as well: web
pages, files imported by URL, inlined images and remote PDFs. Loopback,
private, link-local and metadata addresses are refused, redirects included.
Configured model endpoints do not use this transport and are unaffected.

The guard connects directly. Behind HTTP(S)_PROXY the owner's fetches keep
the proxy and each hop is checked before it is sent instead. Member work is
unchanged.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A fetched web page and a remote PDF were buffered whole, and a node-source
download was size-checked only after it had been: a body with no declared
length could exhaust the Server's memory. All three now stop at their limit
(20 MB for a page, 50 MB for a file).

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Loopback is reachable by every program and every user on the machine, and a
caller there was the owner. The desktop app now starts its Server with a
random token, new on each launch and never written to disk, and adds it to
the requests its own pages make. Without it the Server answers 401.

Agents keep reaching back with the machine credential, and the RFS surface
still accepts nothing else. A web page framed on the Canvas is not given the
token. `--server` and an already running development Server are unchanged.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The threat model listed planned remediation beside existing controls, so it
could not answer whether a mitigation was in the code. Implemented controls
now name where they live, the default local-Server mode is stated as the
scope, and what is not implemented is listed on its own.

Also corrects the reachback token (machine-wide, not scoped), records that
the app strips framing headers for web previews, and that the Windows
installer is signed through ESRP.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
An update was trusted because its hash matched the feed, and the hash comes
from the same release as the installer. The installed app now also checks
that the installer is signed by Microsoft Corporation.

ESRP signs after electron-builder has written the app's update settings, so
the publisher is stated in the configuration instead of being read from a
certificate. The release pipeline fails if the signer is not that publisher:
such a release would install and then refuse every later update.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Seen while running the desktop app end to end: an image node pointing at a
loopback URL was never fetched by the Server, but the Canvas requested it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… and update publisher

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 19, 2026 02:47

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Untrusted workers and preview frames can receive the launch token, DNS failures can allow proxy access to private services, and existing downloads and artifact viewing can break.

8 open issues
What changed in this PR

This PR strengthens security boundaries for the desktop app’s locally started Server and updates the threat model to distinguish implemented controls from remaining gaps.

Changes:

  • Adds per-launch API authentication, permission and download policies, and privileged IPC sender checks.
  • Extends public-network fetch restrictions, bounds response bodies, and restores compatibility with undici 8.
  • Adds Windows update publisher checks and documents the security behavior.
File Description
docs/​desktop-threat-model-attachment.md Separates implemented controls from known gaps.
docs/​architecture/​desktop-startup.md Documents launch tokens and session policies.
docs/​architecture/​desktop-auto-update.md Explains Windows publisher verification.
docs/​architecture/​deployment-security.md Describes inbound authentication and outbound restrictions.
azure-pipelines.yml Passes the installer signer to release verification.
apps/​server/​src/​modules/​security/​outbound.ts Adds deployment-wide restrictions, proxy checks, bounded reads, and dispatcher compatibility.
apps/​server/​src/​modules/​security/​outbound.test.ts Tests guard refusals, proxy behavior, and response limits.
apps/​server/​src/​modules/​preprocessing/​stages/​extract.ts Caps remote PDF response bodies.
apps/​server/​src/​modules/​preprocessing/​loaders/​web.loader.ts Caps fetched HTML bodies.
apps/​server/​src/​modules/​identity/​local.ts Enforces desktop launch-token authentication.
apps/​server/​src/​modules/​identity/​identity.test.ts Tests token admission and existing authentication paths.
apps/​server/​src/​modules/​identity/​config.ts Reads the desktop launch token from configuration.
apps/​server/​src/​modules/​canvas/​import-node-src.ts Enforces file limits while reading downloads.
apps/​desktop/​src/​web-guards.ts Adds token injection and permission/download policies.
apps/​desktop/​src/​web-guards.test.ts Tests session policies and token injection.
apps/​desktop/​src/​updater.ts Validates updater IPC senders.
apps/​desktop/​src/​updater.test.ts Tests rejection of unauthorized updater callers.
apps/​desktop/​src/​main.ts Creates launch tokens and wires security guards.
apps/​desktop/​src/​mac-menu.ts Validates menu IPC senders.
apps/​desktop/​scripts/​esrp-release.test.mjs Tests publisher matching and pipeline integration.
apps/​desktop/​scripts/​esrp-release.mjs Checks signer compatibility before preparing release assets.
apps/​desktop/​electron-builder.yml Configures the accepted Windows update publisher.
.env.example Documents public-network-only content fetching.

Review effort: Balanced

Comment thread apps/desktop/src/web-guards.ts Resolved
Comment thread apps/desktop/src/web-guards.ts Resolved
Comment thread apps/desktop/src/web-guards.ts Outdated
Comment on lines +132 to +133
const document = request.frameUrls.find((url) => /^https?:/i.test(url));
return document === undefined || isServer(document);

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in bfe8851, on the side that grants the origin: a document on the application's origin is never framed with allow-same-origin, whether the Web node names a stored file by key or spells out its absolute URL (livePageSandbox.ts). Such a frame still receives the token so the file's own assets load, but with an opaque origin its reads fail CORS and its writes fail the cross-site guard.

Comment thread apps/desktop/src/main.ts Resolved
Comment thread apps/desktop/src/web-guards.ts Resolved
Comment thread apps/desktop/src/web-guards.ts Resolved
Comment on lines +71 to +75
launchToken &&
!matches(
Buffer.from(header?.(DESKTOP_TOKEN_HEADER) ?? ''),
launchToken,
)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 1a1d3b4. A link that opens one of the Server's raster images in a new window now shows it in an application window on the opener's session, with no preload and no navigation; any other file the Server serves is downloaded. The token never enters a URL. SVG is deliberately treated as a file, since opened as a document it runs script. Verified end to end against the real app.

…mode

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 19, 2026 04:24

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Untrusted frames and workers can gain API access, while proxy DNS failures and unguarded direct connections can bypass private-network restrictions.

9 open issues
1 previously missed issue

In code that hasn't changed since last review

Medium severity Test a successful HTTP response through the dispatcher wrapper

apps/​server/​src/​modules/​security/​outbound.ts:87

[P2] No test exercises a successful HTTP response through Dispatcher1Wrapper: the successful scoped fetch uses data:, and the proxy tests stub fetch. Add a deterministic positive-path test with a controlled connector and assert the response status and body, so failures after an allowed connection cannot leave every public HTTP fetch broken unnoticed.

Review effort: Balanced

A discovered Agent whose CLI supports it was created with auto-approval on,
so content it read could make it run commands unasked. It is now off: the
Agent asks before each tool call and the conversation shows the request.
The user turns auto-approval on in Settings, or for one conversation with
the Agent's own approval selector in the chat input.

Profiles that already exist keep their setting.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 19, 2026 05:18

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Untrusted previews can obtain API tokens, proxy and DNS handling can bypass outbound network restrictions, and the release workflow still publishes unsigned Windows updates that the new publisher check would reject.

9 open issues
2 previously missed issues

In code that hasn't changed since last review

High severity Tag releases publish unsigned Windows installers

apps/​desktop/​electron-builder.yml:133

The active tag-release workflow still builds and publishes an unsigned Windows installer (.github/workflows/release.yml:214-242), independently of the Azure job, and publishes it automatically on tag pushes. Once this publisher check is in installed apps, their next normal release update will therefore be rejected; the Azure signer gate cannot prevent that GitHub release. Please make the release workflow publish the ESRP-signed assets (and wait for its verification), or otherwise stop it from publishing unsigned Windows updates.

Medium severity Tests omit successful HTTP responses and redirect handling

apps/​server/​src/​modules/​security/​outbound.ts:86

The tests never read a successful HTTP(S) response through Dispatcher1Wrapper: the positive member test uses data:, and proxy tests mock fetch. Guard-specific rejection assertions do not exercise response-handler compatibility or the direct dispatcher's redirect path. Add a deterministic HTTP success fixture and a public-to-private redirect case without mocking fetch.

Review effort: Balanced

cxxxxxn (cxxxxxn) and others added 6 commits November 19, 2026 15:33
…at-model-hardening

# Conflicts:
#	apps/server/src/modules/agent/acp/harness-profile-discovery.test.ts
…e browser

A link that opens one of the Server's files in a new window was handed to the
system browser, which holds no launch token and was shown a 401. Raster
images now open in a window of the app; other files the Server serves are
downloaded. A remote Server still authenticates the browser itself.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…app's

A framed page that moved itself to a blob document was judged by the app
frame above it, and any request without a frame was assumed to be the app's.
A document is now judged by its own origin, and a frameless request by the
referrer it states, with only the main process trusted to state none.

Also: downloads of data URLs, which image nodes hold, are allowed again; a
session is guarded once however often its Space is reopened; and the
permission and download policy no longer applies in --server mode.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A Web node whose src spelled out an absolute URL to a stored file was
treated as a remote site and framed with scripts and allow-same-origin: the
file was then the application, free to call every API.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…s set

A configured proxy does not carry every request: NO_PROXY exempts hosts and
a scheme may have none. Those hops used the unguarded global dispatcher, so
a name could resolve publicly for the check and privately for the
connection. Each hop is now sent the way it will actually leave.

An unresolved name is no longer always left to the proxy: one that is
private by construction (a single label, .corp, .internal, .lan and the
like) is refused, since only the proxy's own network could resolve it.

Tests cover the NO_PROXY rules against undici's, and a real response and
redirect through a wrapped dispatcher.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 19, 2026 07:48
@cxxxxxn

Copy link
Copy Markdown
Contributor Author

On the two items from the review overview that have no thread:

  • Tag releases publish unsigned Windows installers. Correct, and it matters once the publisher check ships: an update published by .github/workflows/release.yml would be refused by installed apps. The official release path is azure-pipelines.yml, which signs through ESRP and fails if the signer is not the configured publisher. release.yml is to be disabled; that must happen before the first release that carries this change.
  • Tests omit a successful response through the guarded dispatcher. The guard only admits public addresses, which a test cannot serve. fdd05ae adds a test of the wrapping it depends on (a real response and a real redirect through Dispatcher1Wrapper), and the hop-by-hop path is tested for a public hop redirecting to an exempt one.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Comment thread apps/desktop/electron-builder.yml Resolved
Comment thread apps/desktop/src/desktop-tabs.ts Resolved
Comment thread apps/desktop/src/main.ts Resolved
Comment on lines +23 to +36
/**
* The `sandbox` flags for a live page framed on the Canvas.
*
* A remote site gets `allow-same-origin` so it can read its own cookies and
* storage; being another origin, it still cannot reach the application. A
* document served from the application's own origin never gets it: with
* scripts on it would be the application, free to call every API. That holds
* for a Web node whose `src` spells out an absolute URL to a stored file
* just as for one that names the file by key.
*/
export function livePageSandboxFor(page: LivePage): string {
if (page.interactiveView) return 'allow-scripts allow-forms';
if (page.kind === 'url' && !isOnOrigin(page.src, page.appOrigin))
return 'allow-scripts allow-forms allow-popups allow-same-origin';

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 01dcaf0, at the response rather than the frame: every stored document is now served with the sandbox policy in local mode too, as it already was under per-Space access. A frame that keeps allow-same-origin and is redirected to a stored file therefore still renders it in an opaque origin. Checked end to end: the artifact route answers with sandbox allow-scripts allow-forms allow-popups.

Comment thread apps/desktop/src/web-guards.ts Resolved
Comment thread docs/desktop-threat-model-attachment.md Resolved
cxxxxxn (cxxxxxn) and others added 3 commits November 19, 2026 16:34
…ry mode

The web app frames a stored HTML or SVG file without its origin, but only
the response can make that hold however the file is reached: a remote page
framed with its own origin could redirect to one and run as the application,
with the desktop launch token attached. The sandbox policy that per-Space
access already applied now applies in local mode too.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The window-open handler turned a link to one of the Server's files into a
download or a viewer window, and a page framed on the Canvas with
allow-popups can ask for a window too. The handler now does nothing with
those links. The application's pages ask over the IPC bridge instead, which
a framed page does not have and which checks its sender.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comment on lines +279 to +280
if (!this.remote && (target === 'image' || target === 'file'))
return { action: 'deny' };
...options,
dispatcher: publicOnlyAgent,
} as RequestInit);
await assertPublicHost(url.hostname);
Comment on lines +288 to +289
const files = getElectronBridge()?.files;
if (!files) return false;

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants