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 inopenspec/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
- 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 anOriginheader 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. - A thin, separate, signed Go binary.
vaultfold-native-hostis its own module (cmd/vaultfold-native-host, ingo.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. - 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-largewithout closing), sends the daemonhellowith rolebrowser-hostnaming the browser family and extension id, opens a session, and relays each request as onebrowsercall whose arguments are the JSON translated to a canonical CBOR map, translating results, errors and thelockedandunlockednotifications 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-versionsprints the versions it offers sodoctorcan check it without contacting the daemon. - 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.
- 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.
- 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 wordallowtyped. Until approval the connection can dohelloonly (and the daemonsession-openthe host needs); every other operation,statusincluded, is answereddeniedwith the messageawaiting approval.vaultfold agent approveanswers it from a terminal. - A
browsersession kind. A verified, approved host connection gets one session of kindbrowserper identity, audited asbrowser:<family>:<extension-id>, and the session rules allow it thebrowserverb (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. - Registration is per user and lists published ids only.
vaultfold browser installwrites the per-user manifest for each detected browser (allowed_originson Chromium-family browsers,allowed_extensionson Firefox; the Windows registry values on Windows) from the embedded tablepublished_ids.json. A store id that is stillPENDINGis 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. - 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 statuslists Safari as requiring the desktop app is not built:browser statusdoes 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 installanddoctorown, 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.