Vantage documentation

Security model

Vantage separates three authorities: the native browser application, WebKit's untrusted web-content processes, and deliberately trusted same-user agents. The agent surface is powerful by design; that power is not injected into webpages.

Threat model

Actor/input	Trust	Boundary
Vantage native application	Trusted as user	UI, local state, policy, agent RPC.
Same-user agent	Explicitly trusted	Broad browser authority through local RPC.
Web content	Untrusted	WebKit origin/process/sandbox rules.
Downloads/imports	Untrusted input	Constrained names/paths; content gains no trust.
API responses	Untrusted input	Returned data gains no native authority.

Web content stays in WebKit

WebKitGTK owns HTML parsing, page JavaScript, DOM, origin enforcement, TLS, permissions, rendering and web-process isolation. Vantage does not hand arbitrary page objects or callbacks to privileged native automation code.

Agent RPC is privileged local IPC

The control plane is for software already trusted with the user's desktop/session authority. It is not a website API and should not be exposed as a remote network service.

trusted local agent -> local Vantage RPC -> browser authority
webpage JavaScript  -X-> Vantage RPC
remote website      -X-> local agent socket

Semantic refs fail closed

Snapshot refs are generation-scoped. Vantage does not silently retarget an old ref after DOM mutation. stale_or_missing requires a new observation, reducing accidental action on a changed control.

Direct fetch credential boundary

net.fetch is application-side and bypasses page CORS, but deliberately does not inherit page cookies or browser identity. Agents supply API authorization explicitly.

vant agent fetch https://api.example.com/me '{"headers":{"Authorization":"Bearer TOKEN"}}'

Connections, certificates and permissions

Site information distinguishes ordinary secure connections, insecure connections, source/internal pages and certificate details WebKit makes available. WebKit remains responsible for normal origin, TLS and permission enforcement.

Downloads and hostile filenames

Download names are sanitized and constrained to the selected destination. A browser-created file is still untrusted external content. The same rule applies to history/imported data and agent-fetched responses.

Private windows

Private browsing reduces local persistence; it is not anonymity. Remote sites, network infrastructure and explicitly invoked agents/APIs can still observe data sent to them.

Local state and secrets

History, bookmarks, sessions and settings are local browser data. Treat the Vantage profile and same-user agent socket as user-private resources. Do not place API tokens in documentation, command history or committed scripts.

Updates are part of the boundary

WebKitGTK, GTK and GStreamer are security-sensitive dependencies. Keep the operating system and browser build current through the supported distribution path.