WEFT_OS/docs/architecture.md
Marco Allegretti c28a829624
fix(runtime): enforce effective capability grants per session
Every host import was registered and callable whatever the package
declared, read-only directory capabilities were preopened read-write,
and appd launched packages whose capabilities it could not satisfy. The
fetch import also could not be linked: the host returned a tuple where
the WIT declares the response record, so any component importing
weft:app/fetch failed to instantiate.

One capability vocabulary now lives in weft_ipc_types::capability and
is used by weft-pack, weft-appd and weft-runtime. weft-appd derives a
session's grants once, before the session exists, and refuses the launch
with error 403 when a capability is unknown, unsupported (hw:gpu:*) or
unsatisfiable (documents without an XDG documents directory). The
documents directory now comes from user-dirs.dirs instead of a guessed
~/Documents.

The runtime receives grants explicitly (--grant CAP, --preopen
HOST::GUEST::ro|rw), preopens read-only directories read-only, and checks
the grant on every notifications, clipboard and fetch call. Fetch accepts
only http and https to granted hosts, returns redirects and HTTP error
statuses as responses instead of following or failing them, and bounds
connect time, total time and response size. The file portal takes
read-only directories with --allow-read and refuses writes there.

tests/runtime/check_grants.py runs the real runtime on a probe component
under each kind of grant and checks the outcome of every operation; it
fails when read-only data is writable or an import ignores its grant.
The appd dispatch tests that read WEFT_RUNTIME_BIN now hold the env lock
shared with the tests that set it.
2026-10-09 08:08:58 +00:00

127 lines
9.5 KiB
Markdown

# 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. Accepts JSON-lines requests over a Unix socket. Blocks path traversal. Used by apps that require file access without direct WASI preopens.
### 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_FORWARD` is refused with code 403).
- `{"type":"HELLO","role":"app","session_id":<n>,"token":"<hex>"}` — the token is the session's bridge token, passed to `weft-app-shell` in `WEFT_BRIDGE_TOKEN` and 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, as `APP_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. If any declared capability is unknown, unsupported on this host or cannot be satisfied, `LAUNCH_APP` is answered with an error (code 403) and nothing starts. The runtime does not read the manifest; it receives the grants as arguments:
- `--preopen HOST::GUEST::ro|rw` for each directory, with the access mode the capability names;
- `--grant <capability>` for each host-import capability.
Each host import checks its grant on every call and returns an error naming the missing capability when it is not granted.
| 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 over HTTP or HTTPS |
| `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. Requests time out after 10 seconds to connect and 30 seconds overall, and response bodies are limited to 16 MiB. Fetch requires a runtime built with the `net-fetch` feature.
`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):
1. `$WEFT_APP_STORE` (if set)
2. `~/.local/share/weft/apps/`
3. `/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) |