A component with a host-specific fetch grant could reach another origin by setting its own Host header, and could inject request lines through the method string, which ureq writes unvalidated. Fetch now accepts only standard methods and refuses Host, framing and hop-by-hop headers. Fetch grants accept canonical DNS names and dotted IPv4 addresses only, so a grant can never be written in a form that silently never matches. --preopen split host and guest at the first `::`, so a host path containing `::` widened the preopened directory; it now splits from the right, and appd refuses host paths that are not UTF-8 or contain `::`. appd validated capabilities one at a time, creating the data directory before a later capability was refused, and required HOME even for packages without filesystem capabilities. It now checks every capability first, resolves host directories only when needed, validates the app ID with the rule weft-pack uses (now shared in weft_ipc_types::package), and reports 400, 404, 403 or 500 according to the cause. user-dirs.dirs is read as a shell would: the last assignment wins, $HOME must be followed by a slash, escaped values are ignored and a relative XDG_CONFIG_HOME is not used. The grants probe now also overwrites, renames, removes and creates directories in read-only data, and sends a forged Host header, an injected method and a file: URL; it fails when directory permissions of a read-only preopen are widened or the header check is removed. A new CI job builds the runtime with its engine and fetch support and runs the check. The mount test that sets WEFT_APP_STORE now holds the env lock. Package images are still located separately from directory installs; deriving grants from the verified image is part of resolving one package descriptor.
10 KiB
WEFT OS Architecture
Overview
WEFT OS is a Wayland compositor and application runtime where every app is a WebAssembly component served via a Servo-rendered WebView. The system has no ambient authority: capabilities are declared in wapp.toml, verified at install time, and enforced at runtime.
Components
weft-compositor
Smithay-based Wayland compositor. Implements the zweft-shell-unstable-v1 protocol extension, which allows shell clients (servo-shell, app-shell) to register their surfaces as typed shell slots. Supports DRM/KMS and winit (software/dev) backends.
weft-servo-shell
System UI host. Renders one WebView pointing at system-ui.html using the embedded Servo engine (feature-gated behind servo-embed). Connects to the compositor as window type panel. Dispatches the zweft_shell_manager_v1 event queue each frame. Forwards navigation gestures received from the compositor to weft-appd over WebSocket. Reads the appd WebSocket port and system token from $XDG_RUNTIME_DIR/weft/ and hands both to the page through window.weftAppdEndpoint(port, token); the shell hands the token only to the system UI document and denies top-level navigation away from it, and the launcher shows package names as text, never markup.
weft-app-shell
Per-application Servo host. Spawned by weft-appd after the Wasm runtime signals READY. Takes <app_id> and <session_id> as arguments. Resolves weft-app://<app_id>/ui/index.html and injects the weftIpc WebSocket bridge into the page. The bridge authenticates with the per-session token from WEFT_BRIDGE_TOKEN and can only exchange messages with its own session. It is installed only in top-level documents inside the application's UI directory, and top-level navigation outside that directory is denied; framed documents never receive the bridge. Registers with the compositor as window type application. Exits when the appd session ends.
weft-appd
Session supervisor. Listens on a Unix socket (MessagePack protocol) and a WebSocket port (JSON). For each session: spawns weft-runtime and waits for its READY, spawns weft-app-shell (WEFT_APP_SHELL_BIN is required) and waits for its READY, and only then reports the session running (APP_READY). A child reports readiness by printing READY <token> on stdout, where the token is a random per-session value appd passes in WEFT_READY_TOKEN; Wasm guests and pages share those stdout streams but cannot read the token, so their output cannot fake readiness. Each wait times out after 30 seconds. If either child fails to start, fails to become ready or exits, or the session is terminated, the whole session is stopped: both children, the file portal, the compositor association and any image mount are released. Manages the per-session IPC relay and applies cgroup resource limits to the runtime via systemd-run when available.
weft-runtime
WASI Preview 2 + Component Model execution host (Wasmtime 30). Loads app.wasm from the installed package directory. Provides host imports for weft:app/notify, weft:app/ipc, weft:app/fetch, weft:app/notifications, and weft:app/clipboard. Preopens filesystem paths according to capabilities declared in wapp.toml.
weft-pack
Package management CLI. Subcommands: check (validate wapp.toml + wasm module), sign (Ed25519 signature), verify (verify signature), generate-key, install, uninstall, list, build-image (EROFS dm-verity), info.
weft-file-portal
Per-session file proxy. Runs as a separate process with a path allowlist derived from the session's directory grants; read-only grants (--allow-read) refuse writes. Paths are checked lexically, so .. is blocked but symbolic links are followed. Accepts JSON-lines requests over a Unix socket. Components cannot currently reach that socket, because the runtime grants them no socket access.
weft-mount-helper
Setuid helper binary. Calls veritysetup and mounts EROFS images for dm-verity-protected packages.
Process Topology
systemd
├── weft-compositor (user)
├── weft-servo-shell (user, after compositor)
└── weft-appd (user, after compositor + servo-shell)
└── per-session:
├── weft-runtime <app_id> <session_id> [--preopen HOST::GUEST::ro|rw]... [--grant CAP]... [--ipc-socket ...]
├── weft-app-shell <app_id> <session_id>
└── weft-file-portal <socket> [--allow ...] [--allow-read ...]
IPC
| Channel | Protocol | Purpose |
|---|---|---|
| weft-appd Unix socket | MessagePack | appd ↔ other system daemons |
| weft-appd WebSocket (:7410) | JSON | system-ui.html and servo-shell ↔ appd (system role: gestures, app lifecycle); app pages ↔ their session (app role) |
| per-session IPC socket | newline-delimited JSON | weft-runtime ↔ weft-app-shell (weft:app/ipc) |
| weft-file-portal socket | JSON-lines | weft-runtime ↔ file proxy |
WebSocket roles
Every WebSocket connection must complete the upgrade and send HELLO as its first message within 5 seconds, or appd closes it; a first message that is not a valid HELLO is answered with an error (code 401) before the connection is closed. Messages are limited to 1 MiB.
{"type":"HELLO","role":"system","token":"<hex>"}— the token is the content of$XDG_RUNTIME_DIR/weft/appd.systoken(mode 0600), regenerated each time appd starts. A system client may launch, terminate and query sessions. It receives lifecycle broadcasts but never application messages, and cannot inject them (IPC_FORWARDis refused with code 403).{"type":"HELLO","role":"app","session_id":<n>,"token":"<hex>"}— the token is the session's bridge token, passed toweft-app-shellinWEFT_BRIDGE_TOKENand distinct from its readiness token. An app client may only send{"type":"APP_MESSAGE","payload":"<string>"}(at most 64 KiB, no newlines); the payload goes to its own session's Wasm component. It receives only its own session's replies, asAPP_MESSAGE, and is disconnected when the session stops.
Capability Enforcement
Capabilities are declared in wapp.toml under [package] capabilities. One vocabulary (weft_ipc_types::capability) is used by weft-pack check, which rejects unknown strings, by weft-appd, which derives the session's effective grants, and by weft-runtime, which enforces them.
weft-appd derives grants once, before a session exists. LAUNCH_APP is answered with an error and nothing starts when the app ID is malformed (code 400), the package is not installed (404), a declared capability is unknown, unsupported on this host or cannot be satisfied (403), or the host cannot provide the resources (500, for example without HOME). All capabilities are checked before the app's data directory is created. Without WEFT_RUNTIME_BIN, appd starts no processes and derives no grants. The runtime does not read the manifest; it receives the grants as arguments:
--preopen HOST::GUEST::ro|rwfor each directory, with the access mode the capability names;--grant <capability>for each host-import capability.
Each capability-controlled host import (fetch, notifications, clipboard) checks its grant on every call and returns an error naming the missing capability when it is not granted. notify and ipc need no capability.
| Capability | Effect |
|---|---|
fs:read:app-data / fs:rw:app-data |
Preopen ~/.local/share/weft/apps/<id>/data as /data, read-only or read-write |
fs:read:xdg-documents / fs:rw:xdg-documents |
Preopen the documents directory from the XDG user-dirs configuration (XDG_DOCUMENTS_DIR) as /xdg/documents; the launch fails when none is configured |
net:fetch:<host> |
weft:app/fetch to that exact host (a lowercase DNS name or dotted IPv4 address) over HTTP or HTTPS, on any port |
net:fetch:* |
weft:app/fetch to any host |
sys:notifications |
weft:app/notifications |
sys:clipboard:read / sys:clipboard:write |
weft:app/clipboard#read / #write |
hw:gpu:compute / hw:gpu:render |
Not supported; the launch fails |
Fetch does not follow redirects: a redirect is returned to the component as a response, so every destination it requests is checked against its grants. HTTP error statuses are responses too; only policy and transport failures are errors. Only the methods GET, HEAD, POST, PUT, PATCH, DELETE and OPTIONS are accepted, and a component cannot set Host, Content-Length, Transfer-Encoding or other hop-by-hop headers. Connecting times out after 10 seconds and the whole request after 30 seconds, not counting DNS resolution; response bodies are limited to 16 MiB. Fetch requires a runtime built with the net-fetch feature.
Fetch grants name hosts, not addresses: ports are not restricted, and a host that resolves to a loopback or private address (or net:fetch:*) can reach local services. IPv6 literals cannot be granted.
tests/runtime/check_grants.py runs the real runtime on a probe component (tests/components/grants-probe) under each kind of grant.
Package Format
<app_id>/
wapp.toml — manifest (id, name, version, capabilities, runtime.module, ui.entry)
app.wasm — WASI Component Model binary
ui/
index.html — entry point served by weft-app-shell
signature.sig — Ed25519 signature over SHA-256 of (wapp.toml + app.wasm)
Package store roots (in priority order):
$WEFT_APP_STORE(if set)~/.local/share/weft/apps//usr/share/weft/apps/
Environment Variables
| Variable | Default | Description |
|---|---|---|
WEFT_RUNTIME_BIN |
— | Path to weft-runtime binary |
WEFT_APP_SHELL_BIN |
— | Path to weft-app-shell binary; required to launch apps |
WEFT_READY_TOKEN |
set by appd | Per-session readiness token passed to weft-runtime and weft-app-shell |
WEFT_BRIDGE_TOKEN |
set by appd | Per-session token weft-app-shell uses to join its session on the appd WebSocket |
WEFT_FILE_PORTAL_BIN |
— | Path to weft-file-portal binary |
WEFT_MOUNT_HELPER |
— | Path to weft-mount-helper binary |
WEFT_APP_STORE |
— | Override package store root |
WEFT_APPD_SOCKET |
— | Unix socket path for weft-appd |
WEFT_APPD_WS_PORT |
7410 |
WebSocket port for weft-appd |
WEFT_EGL_RENDERING |
— | Set to 1 to use EGL rendering in Servo shell |
WEFT_DISABLE_CGROUP |
— | Set to disable systemd-run cgroup wrapping |
WEFT_FILE_PORTAL_SOCKET |
— | Path forwarded to app runtime for file portal |
XDG_RUNTIME_DIR |
— | Standard XDG runtime dir (sockets written here) |