2026-03-12 14:41:33 +00:00
# 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
2026-10-09 07:53:23 +00:00
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.
2026-03-12 14:41:33 +00:00
### weft-app-shell
2026-10-09 07:53:23 +00:00
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.
2026-03-12 14:41:33 +00:00
### weft-appd
fix(appd): report sessions running only after the UI host is ready
weft-appd marked a session Running and broadcast APP_READY as soon as the
runtime printed READY, then started weft-app-shell with its output
discarded and never watched it. A session with no UI, a UI host that
failed to start, or one that crashed was still reported running. Early
failure paths skipped parts of the cleanup: the image mount was not
unmounted, the compositor association was not released, and the abort
sender leaked on spawn failure. Readiness was any stdout line equal to
READY, which a Wasm guest (inherited stdout) or a page (window.alert
writes to the app shell's stdout) could print.
Now a session becomes Running only after the runtime and then the app
shell report readiness, each within 30 s; WEFT_APP_SHELL_BIN is required
and checked before anything starts. After that, the runtime exiting, the
app shell exiting or a terminate request ends the session. Every exit
path goes through one teardown that kills both children, releases the
compositor association, unmounts the image, stops the file portal and
broadcasts Stopped.
Readiness uses a per-session random token passed to both children in
WEFT_READY_TOKEN. weft-runtime and weft-app-shell print READY <token>,
and appd accepts only a line ending with it; guests receive only the
variables the runtime names and pages cannot read the host environment.
Child output is read in bounded, lossily decoded lines, so invalid UTF-8
or long lines no longer stop the readers. Compositor notifications use
try_send so a disconnected compositor cannot stall teardown, and all
children are killed if the supervisor is dropped.
The IPC relay is not yet owned by the session, and children are killed
without a graceful period.
Validation:
- cargo test -p weft-appd (43 passed); new tests cover: not ready until
the app shell is ready, runtime exit before that, no app shell
configured (runtime never starts), app shell exit ending a running
session with the runtime process gone, and READY lines without the
token; they fail against the previous supervisor
- end to end with weft-compositor (nested), weft-appd, weft-runtime
(wasmtime-runtime) and weft-app-shell: the Counter demo reaches
APP_READY and is on screen; a page that prints a READY line through
alert and never loads is stopped after 30 s without APP_READY;
terminate leaves no child processes
- clippy -D warnings and fmt --check for weft-appd and weft-runtime
2026-10-09 01:41:09 +00:00
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.
2026-03-12 14:41:33 +00:00
### 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
fix(runtime): close fetch and preopen gaps in grant enforcement
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.
2026-10-09 08:25:40 +00:00
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.
2026-03-12 14:41:33 +00:00
### 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:
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
├── weft-runtime < app_id > < session_id > [--preopen HOST::GUEST::ro|rw]... [--grant CAP]... [--ipc-socket ...]
2026-03-12 14:41:33 +00:00
├── weft-app-shell < app_id > < session_id >
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
└── weft-file-portal < socket > [--allow ...] [--allow-read ...]
2026-03-12 14:41:33 +00:00
```
## IPC
| Channel | Protocol | Purpose |
|---|---|---|
| weft-appd Unix socket | MessagePack | appd ↔ other system daemons |
2026-10-09 07:45:49 +00:00
| weft-appd WebSocket (:7410) | JSON | system-ui.html and servo-shell ↔ appd (system role: gestures, app lifecycle); app pages ↔ their session (app role) |
2026-03-12 14:41:33 +00:00
| 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 |
2026-10-09 07:45:49 +00:00
### 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.
2026-03-12 14:41:33 +00:00
## Capability Enforcement
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
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.
fix(appd): keep app data apart from installed packages
App data lived in ~/.local/share/weft/apps/<id>/data, inside the user
package store under the installed package directory. Uninstalling a
package deleted its data, and launching a package installed elsewhere
created that directory, after which installing the package for the user
failed because its directory already existed.
App data now lives in $XDG_DATA_HOME/weft/app-data/<id>, one shared
rule in weft_ipc_types::package, and is made private (0700) on every
launch. Data in the earlier location is moved there in one rename on the
first launch with an app-data capability, and by weft-pack before it
uninstalls a package or installs over a directory holding only data. If
both locations hold data, nothing is moved: the launch is refused with
409 and weft-pack stops, so neither copy is lost or merged.
tests/frame/check_app_data.py launches the Notes demo on the nested
desktop with notes in the earlier location and checks that they arrive
byte for byte (including a literal backslash sequence and non-ASCII
text), that the old directory is gone, that the new one is 0700 and that
a second copy makes the next launch fail with 409 without changing
either. The weft-pack tests that change the environment now share a lock.
2026-10-09 08:43:42 +00:00
`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), app data exists in both the current and the earlier location (409), 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:
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
- `--preopen HOST::GUEST::ro|rw` for each directory, with the access mode the capability names;
- `--grant <capability>` for each host-import capability.
fix(runtime): close fetch and preopen gaps in grant enforcement
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.
2026-10-09 08:25:40 +00:00
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.
2026-03-12 14:41:33 +00:00
| Capability | Effect |
|---|---|
fix(appd): keep app data apart from installed packages
App data lived in ~/.local/share/weft/apps/<id>/data, inside the user
package store under the installed package directory. Uninstalling a
package deleted its data, and launching a package installed elsewhere
created that directory, after which installing the package for the user
failed because its directory already existed.
App data now lives in $XDG_DATA_HOME/weft/app-data/<id>, one shared
rule in weft_ipc_types::package, and is made private (0700) on every
launch. Data in the earlier location is moved there in one rename on the
first launch with an app-data capability, and by weft-pack before it
uninstalls a package or installs over a directory holding only data. If
both locations hold data, nothing is moved: the launch is refused with
409 and weft-pack stops, so neither copy is lost or merged.
tests/frame/check_app_data.py launches the Notes demo on the nested
desktop with notes in the earlier location and checks that they arrive
byte for byte (including a literal backslash sequence and non-ASCII
text), that the old directory is gone, that the new one is 0700 and that
a second copy makes the next launch fail with 409 without changing
either. The weft-pack tests that change the environment now share a lock.
2026-10-09 08:43:42 +00:00
| `fs:read:app-data` / `fs:rw:app-data` | Preopen the app's data directory (see *App data* ) as `/data` , read-only or read-write |
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
| `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 |
fix(runtime): close fetch and preopen gaps in grant enforcement
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.
2026-10-09 08:25:40 +00:00
| `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 |
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
| `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 |
fix(runtime): close fetch and preopen gaps in grant enforcement
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.
2026-10-09 08:25:40 +00:00
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.
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
`tests/runtime/check_grants.py` runs the real runtime on a probe component (`tests/components/grants-probe`) under each kind of grant.
2026-03-12 14:41:33 +00:00
## 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/`
fix(appd): keep app data apart from installed packages
App data lived in ~/.local/share/weft/apps/<id>/data, inside the user
package store under the installed package directory. Uninstalling a
package deleted its data, and launching a package installed elsewhere
created that directory, after which installing the package for the user
failed because its directory already existed.
App data now lives in $XDG_DATA_HOME/weft/app-data/<id>, one shared
rule in weft_ipc_types::package, and is made private (0700) on every
launch. Data in the earlier location is moved there in one rename on the
first launch with an app-data capability, and by weft-pack before it
uninstalls a package or installs over a directory holding only data. If
both locations hold data, nothing is moved: the launch is refused with
409 and weft-pack stops, so neither copy is lost or merged.
tests/frame/check_app_data.py launches the Notes demo on the nested
desktop with notes in the earlier location and checks that they arrive
byte for byte (including a literal backslash sequence and non-ASCII
text), that the old directory is gone, that the new one is 0700 and that
a second copy makes the next launch fail with 409 without changing
either. The weft-pack tests that change the environment now share a lock.
2026-10-09 08:43:42 +00:00
## App data
fix(appd): move only real app data and never replace a directory
weft-pack treated any top-level data directory in a package as app
data from the earlier layout, in every store and for every app: a
package shipping data/ lost that content to the app data directory on
uninstall and could then no longer be uninstalled. Data is now moved
only from ~/.local/share/weft/apps/<id>/data, the only place earlier
versions wrote it, and only for packages declaring an app-data
capability; packages may no longer contain a top-level data entry.
The move left an empty package directory behind, which then blocked
weft-pack install although nothing was listed; an emptied package
directory is now removed, and install accepts an empty leftover. The
rename uses RENAME_NOREPLACE, so a target created after the check is
reported as a conflict instead of being replaced, and a move across
filesystems is refused with a message naming both locations instead of
a bare OS error. Directories moved by weft-pack are made private too,
and a symbolic link at the target is refused rather than followed.
The system UI now shows launch refusals, which it only logged, and the
weft-appd unit may write under ~/.local/share/weft, which
ProtectSystem=strict made read-only. check_app_data.py also types into
Notes after the move and requires the save to reach the moved file, and
checks that no empty package directory remains.
2026-10-09 08:52:09 +00:00
Each app's private data lives in `$XDG_DATA_HOME/weft/app-data/<id>` (`~/.local/share/weft/app-data/< id > ` by default), apart from installed packages. Installing, updating or uninstalling a package never removes it. `weft-appd` creates the directory when a session with an app-data capability starts and makes it accessible only to the user (mode 0700). `weft-appd` and `weft-pack` must run with the same `HOME` and `XDG_DATA_HOME` to agree on this location; the systemd unit allows `weft-appd` to write under `~/.local/share/weft` .
fix(appd): keep app data apart from installed packages
App data lived in ~/.local/share/weft/apps/<id>/data, inside the user
package store under the installed package directory. Uninstalling a
package deleted its data, and launching a package installed elsewhere
created that directory, after which installing the package for the user
failed because its directory already existed.
App data now lives in $XDG_DATA_HOME/weft/app-data/<id>, one shared
rule in weft_ipc_types::package, and is made private (0700) on every
launch. Data in the earlier location is moved there in one rename on the
first launch with an app-data capability, and by weft-pack before it
uninstalls a package or installs over a directory holding only data. If
both locations hold data, nothing is moved: the launch is refused with
409 and weft-pack stops, so neither copy is lost or merged.
tests/frame/check_app_data.py launches the Notes demo on the nested
desktop with notes in the earlier location and checks that they arrive
byte for byte (including a literal backslash sequence and non-ASCII
text), that the old directory is gone, that the new one is 0700 and that
a second copy makes the next launch fail with 409 without changing
either. The weft-pack tests that change the environment now share a lock.
2026-10-09 08:43:42 +00:00
fix(appd): move only real app data and never replace a directory
weft-pack treated any top-level data directory in a package as app
data from the earlier layout, in every store and for every app: a
package shipping data/ lost that content to the app data directory on
uninstall and could then no longer be uninstalled. Data is now moved
only from ~/.local/share/weft/apps/<id>/data, the only place earlier
versions wrote it, and only for packages declaring an app-data
capability; packages may no longer contain a top-level data entry.
The move left an empty package directory behind, which then blocked
weft-pack install although nothing was listed; an emptied package
directory is now removed, and install accepts an empty leftover. The
rename uses RENAME_NOREPLACE, so a target created after the check is
reported as a conflict instead of being replaced, and a move across
filesystems is refused with a message naming both locations instead of
a bare OS error. Directories moved by weft-pack are made private too,
and a symbolic link at the target is refused rather than followed.
The system UI now shows launch refusals, which it only logged, and the
weft-appd unit may write under ~/.local/share/weft, which
ProtectSystem=strict made read-only. check_app_data.py also types into
Notes after the move and requires the save to reach the moved file, and
checks that no empty package directory remains.
2026-10-09 08:52:09 +00:00
Earlier versions kept app data inside the user package store, in `~/.local/share/weft/apps/<id>/data` , for apps declaring an app-data capability. That directory is moved to the new location in a single rename, which never replaces an existing directory:
- by `weft-appd` , on the first launch with an app-data capability;
- by `weft-pack uninstall` and `weft-pack install` , before they touch the package directory, for packages in the user store that declare an app-data capability.
A package directory left empty by the move is removed. Nothing is moved, and `weft-pack` stops or the launch is refused, when the new location already exists, even empty (error 409), when the old one is not a plain directory, or when the two are on different filesystems (error 500); the message names both locations so the user can keep one copy and remove the other. The system UI shows such refusals. Packages cannot contain a top-level `data` entry, so package content is never taken for app data. `tests/frame/check_app_data.py` checks that existing Notes data arrives byte for byte, that the Notes session then reads and saves it, and that a conflict is refused.
fix(appd): keep app data apart from installed packages
App data lived in ~/.local/share/weft/apps/<id>/data, inside the user
package store under the installed package directory. Uninstalling a
package deleted its data, and launching a package installed elsewhere
created that directory, after which installing the package for the user
failed because its directory already existed.
App data now lives in $XDG_DATA_HOME/weft/app-data/<id>, one shared
rule in weft_ipc_types::package, and is made private (0700) on every
launch. Data in the earlier location is moved there in one rename on the
first launch with an app-data capability, and by weft-pack before it
uninstalls a package or installs over a directory holding only data. If
both locations hold data, nothing is moved: the launch is refused with
409 and weft-pack stops, so neither copy is lost or merged.
tests/frame/check_app_data.py launches the Notes demo on the nested
desktop with notes in the earlier location and checks that they arrive
byte for byte (including a literal backslash sequence and non-ASCII
text), that the old directory is gone, that the new one is 0700 and that
a second copy makes the next launch fail with 409 without changing
either. The weft-pack tests that change the environment now share a lock.
2026-10-09 08:43:42 +00:00
2026-03-12 14:41:33 +00:00
## Environment Variables
| Variable | Default | Description |
|---|---|---|
| `WEFT_RUNTIME_BIN` | — | Path to `weft-runtime` binary |
fix(appd): report sessions running only after the UI host is ready
weft-appd marked a session Running and broadcast APP_READY as soon as the
runtime printed READY, then started weft-app-shell with its output
discarded and never watched it. A session with no UI, a UI host that
failed to start, or one that crashed was still reported running. Early
failure paths skipped parts of the cleanup: the image mount was not
unmounted, the compositor association was not released, and the abort
sender leaked on spawn failure. Readiness was any stdout line equal to
READY, which a Wasm guest (inherited stdout) or a page (window.alert
writes to the app shell's stdout) could print.
Now a session becomes Running only after the runtime and then the app
shell report readiness, each within 30 s; WEFT_APP_SHELL_BIN is required
and checked before anything starts. After that, the runtime exiting, the
app shell exiting or a terminate request ends the session. Every exit
path goes through one teardown that kills both children, releases the
compositor association, unmounts the image, stops the file portal and
broadcasts Stopped.
Readiness uses a per-session random token passed to both children in
WEFT_READY_TOKEN. weft-runtime and weft-app-shell print READY <token>,
and appd accepts only a line ending with it; guests receive only the
variables the runtime names and pages cannot read the host environment.
Child output is read in bounded, lossily decoded lines, so invalid UTF-8
or long lines no longer stop the readers. Compositor notifications use
try_send so a disconnected compositor cannot stall teardown, and all
children are killed if the supervisor is dropped.
The IPC relay is not yet owned by the session, and children are killed
without a graceful period.
Validation:
- cargo test -p weft-appd (43 passed); new tests cover: not ready until
the app shell is ready, runtime exit before that, no app shell
configured (runtime never starts), app shell exit ending a running
session with the runtime process gone, and READY lines without the
token; they fail against the previous supervisor
- end to end with weft-compositor (nested), weft-appd, weft-runtime
(wasmtime-runtime) and weft-app-shell: the Counter demo reaches
APP_READY and is on screen; a page that prints a READY line through
alert and never loads is stopped after 30 s without APP_READY;
terminate leaves no child processes
- clippy -D warnings and fmt --check for weft-appd and weft-runtime
2026-10-09 01:41:09 +00:00
| `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` |
2026-10-09 07:45:49 +00:00
| `WEFT_BRIDGE_TOKEN` | set by appd | Per-session token `weft-app-shell` uses to join its session on the appd WebSocket |
2026-03-12 14:41:33 +00:00
| `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) |