Skip to content

0047: Native messaging and a thin signed host reach the daemon

  • Status: accepted (add-browser-extension archived 2026-10-30)
  • Date: 2026-10-27
  • Change: add-browser-extension (design in openspec/changes/add-browser-extension/design.md, "Decisions" and "Group 1", "Group 2" and "Group 10 decisions")
  • Builds on: 0028, 0038

Context

The browser extension needs to reach the agent daemon, the only holder of unlocked key material (ADR 0011). A web page can reach anything a browser extension can reach by a network route, so the transport decides who else can talk to the daemon on the extension's behalf, and how the daemon can tell which extension is asking. The choices were a localhost HTTP or WebSocket listener, or the browser's Native Messaging API.

Decision

  1. Native Messaging, no port. The extension reaches the daemon only through the browser's Native Messaging API, connected to the host app.vaultfold.native_host. No party opens a TCP or UDP port for the extension. A localhost listener would have to defend against every web page in every browser on the machine (cross-site WebSocket hijacking, DNS rebinding, port scanning, other local users) and has no strong answer to "which extension is this", because an Origin header is only as good as the client that sends it. With Native Messaging the browser launches the host only for extension ids listed in the host manifest, passes the verified id on the command line, and speaks over stdio, which nothing else can reach.
  2. A thin, separate, signed Go binary. vaultfold-native-host is its own module (cmd/vaultfold-native-host, in go.work) whose only imports beyond the standard library are the core protocol packages (core/agentproto, core/browserproto, core/canon) and two third-party modules (go-winio, x/sys), so it pulls none of the CLI's code. A browser launches a manifest path with fixed arguments, so the host has to be an executable in its own right; a separate binary also gives the daemon a caller identity it can restrict to browser requests instead of the full CLI identity. It ships in every CLI channel and is signed with the project identity.
  3. The host translates; it does not interpret. Following ADR 0028 ("One protocol only") the daemon reads only its own CBOR frames. The host terminates the extension's JSON framing (4-byte little-endian length, 1 MiB cap in both directions, message-too-large without closing), sends the daemon hello with role browser-host naming the browser family and extension id, opens a session, and relays each request as one browser call whose arguments are the JSON translated to a canonical CBOR map, translating results, errors and the locked and unlocked notifications back (core/browserproto). It parses envelopes and encodings and never an operation's meaning; it holds no key, caches nothing and logs no message body. It exits when the browser closes its standard input. --protocol-versions prints the versions it offers so doctor can check it without contacting the daemon.
  4. The daemon trusts nothing the host says about the browser. It resolves the host's parent process itself and checks that it is a supported browser of the family reported (by executable path and, on macOS and Windows, code-signing identity). It does trust the host's report of the extension id, which is sound because the host is a project-signed binary whose parent is a verified browser, and the browser passes only ids the manifest allows. On Linux, where there is no code signature, a host passes when its running image is a regular, non-writable file owned by the user or root that sits beside the daemon, keyed by its hash.
  5. Caller identity is the triple (host signature, browser, extension id). The allowlist (the daemon's existing sealed one) is keyed on the triple, so approving the extension in Chrome does not approve it in Edge, a sideloaded build with another id is a separate caller, and revoking one leaves the others. Firefox release, Developer Edition and Nightly are distinct browsers. Profiles are not distinguishable from outside the browser and are not part of the key.
  6. First contact is a prompt the human answers in the daemon's own UI. An unknown triple is queued as a first-contact approval at its hello. A published vaultfold id is a yes/no; any other id needs the word allow typed. Until approval the connection can do hello only (and the daemon session-open the host needs); every other operation, status included, is answered denied with the message awaiting approval. vaultfold agent approve answers it from a terminal.
  7. A browser session kind. A verified, approved host connection gets one session of kind browser per identity, audited as browser:<family>:<extension-id>, and the session rules allow it the browser verb (plus status, lock and pending) and refuse that verb to every other kind. Agent sessions cannot drive the extension (see harness-integration), the host refuses to connect when its parent browser or its own environment shows automation, and the daemon repeats both checks.
  8. Registration is per user and lists published ids only. vaultfold browser install writes the per-user manifest for each detected browser (allowed_origins on Chromium-family browsers, allowed_extensions on Firefox; the Windows registry values on Windows) from the embedded table published_ids.json. A store id that is still PENDING is never written. Snap Firefox needs the system-wide manifest and --system; Snap Chromium and Flatpak browsers are reported unsupported, because their confinement blocks native hosts.
  9. Safari is not served by this transport. A Safari Web Extension must live inside a signed macOS app, whose native side is an app extension, not a stdio host. The Safari build target exists; the XPC bridge that plays the host's role is built with the desktop app. The spec scenario that vaultfold browser status lists Safari as requiring the desktop app is not built: browser status does not mention Safari yet.

Consequences

  • Nothing on the machine listens for the extension. The attack surface is the manifest (who may launch the host) and the daemon's caller checks.
  • The identity is the id the browser passes. A same-user process that enables developer mode and installs a copy under a published id is served as that extension once the human approved the id in that browser. The typed confirmation for unpublished ids, the refusal of developer flags and the per-channel Firefox identities narrow this and do not close it (threat model, "The browser extension").
  • Linux hosts are checked by image and hash, not signature, and a mount namespace trick is an accepted residual (design.md "Group 2 decisions" 18).
  • Every browser needs its own manifest, which browser install and doctor own, and sandboxed Linux browsers are partly unsupported.
  • The protocol between the extension and the host is its own versioned document (docs/protocol/browser-v1.md), independent of the CLI.