WEFT_OS/README.md

106 lines
5 KiB
Markdown
Raw Normal View History

# WEFT OS
WEFT OS is a Wayland compositor and application runtime where every app is a WebAssembly component rendered in an isolated Servo WebView. No capability is granted by default; all resource access is declared in a per-app manifest and enforced at runtime.
## What is implemented
**Compositor** — `weft-compositor` is a Smithay-based Wayland compositor with DRM/KMS and winit backends. It implements the `zweft-shell-unstable-v1` protocol extension, which typed shell slots (panel, application) register against.
**System shell** — `weft-servo-shell` embeds Servo (feature-gated, `--features servo-embed`) and renders `system-ui.html` as a Wayland panel. Without `servo-embed`, the binary builds as a no-op stub. Navigation gestures from the compositor are forwarded to `weft-appd` over WebSocket.
**App shell** — `weft-app-shell` is a per-process Servo host for application WebViews. It resolves `weft-app://<id>/ui/index.html`, injects a `weftIpc` WebSocket bridge into the page, and registers with the compositor as an application surface. Also feature-gated behind `servo-embed`.
**App daemon** — `weft-appd` supervises sessions: spawns `weft-runtime`, waits for READY, spawns `weft-app-shell`, manages the per-session IPC relay between the Wasm component and the WebView, and handles session teardown. Wraps processes in systemd scopes (`CPUQuota=200%`, `MemoryMax=512M`) when available.
**Runtime** — `weft-runtime` runs WASI Component Model binaries under Wasmtime 30 (`--features wasmtime-runtime`). Provides `weft:app/notify`, `weft:app/ipc`, `weft:app/fetch`, `weft:app/notifications`, and `weft:app/clipboard` host imports. Preopens filesystem paths according to declared capabilities.
**Package management** — `weft-pack` handles check, sign, verify, install, uninstall, list, build-image (EROFS dm-verity), and info. Validates capability strings at check time.
**File portal** — `weft-file-portal` is a per-session file proxy with a path allowlist and `..` blocking.
**Mount helper** — `weft-mount-helper` is a setuid helper for EROFS dm-verity mount/umount via `veritysetup`.
**Demo apps** — `examples/org.weft.demo.counter` and `examples/org.weft.demo.notes` are pre-built Wasm Component binaries (`wasm32-wasip2`, wit-bindgen 0.53) with HTML UIs, signed with a committed demo keypair.
## Repository layout
```
crates/ Rust workspace members
examples/ Demo app packages (wasm32-wasip2, not workspace members)
keys/ Demo Ed25519 keypair
protocol/ zweft-shell-unstable-v1 Wayland protocol XML
infra/
nixos/ NixOS VM configuration and package derivations
scripts/ check.ps1, check.sh
shell/ system-ui.html, weft-ui-kit.js
systemd/ service unit files
vm/ build.sh, run.sh (QEMU)
docs/
architecture.md Component map, IPC, capability table, env vars
security.md Capability model, process isolation, SpiderMonkey security boundary
building.md Build instructions for all targets
```
## Building
Linux system packages required (openSUSE):
```sh
sudo zypper install -y \
libwayland-devel libxkbcommon-devel libglvnd-devel \
libgbm-devel libdrm-devel libinput-devel seatd-devel libudev-devel \
systemd-devel pkg-config clang cmake python3
```
Build non-Servo crates:
```sh
cargo build --workspace --exclude weft-servo-shell --exclude weft-app-shell
```
Build Linux-only crates (no Servo):
```sh
cargo build -p weft-compositor -p weft-servo-shell -p weft-app-shell
```
Build with Servo embedding (30–60 min, requires clang + python3):
```sh
cargo build -p weft-servo-shell --features servo-embed
cargo build -p weft-app-shell --features servo-embed
```
See `docs/building.md` for full instructions including Wasm component builds, NixOS VM, and signing.
## CI
docs: add engineering contract, contributor toolkit and templates Add AGENTS.md as the single engineering contract: sources of truth, evidence and proof requirements, ownership, working modes, the reviewed change loop, maintenance isolation, decision authority, dependency and fork rules, the 0.0.x to 0.1.0 release progression, and branch and publication rules. Add .agents/ with scope, implement, verify, maintenance and release procedures; reviewer, architecture debt scout, simplicity and refactoring roles; skills for the compositor, Servo rendering, runtime capabilities, appd sessions, packages and data, Linux deployment, integration verification and documentation; and verify.py, which runs the existing check profiles with --locked from any directory, stops on the first failure and supports --dry-run. check_toolkit.py validates local links and heading anchors, metadata, catalog coverage and issue forms. A new contributor-toolkit CI job runs both. The structure follows the Resina Design System toolkit at 1e768064f57a1e403ab271822383e732795905a6, adapted to WEFT. Validation, against the committed lockfiles: - verify.py toolkit: checker passes, 28 runner/checker tests pass - verify.py portable, demos, packages: pass - verify.py linux, runtime, servo-embed: fail on existing defects (clippy collapsible_if in the winit backend, three clippy lints in weft-runtime with wasmtime-runtime, and an E0308 in the selected Servo revision's servo-layout); the runner reports the failing status Add CONTRIBUTING.md, issue forms for defects and changes, maintenance problems and decisions of direction, and a pull request template asking for ownership, proof and the validation actually performed. README.md links the contribution guide.
2026-10-08 23:40:08 +00:00
Four jobs on every push and pull request:
- `cross-platform` — fmt, clippy, tests on Ubuntu and Windows
- `linux-only` — clippy and tests for compositor and shell crates
- `servo-embed-linux` — `cargo check --features servo-embed` for both servo crates
docs: add engineering contract, contributor toolkit and templates Add AGENTS.md as the single engineering contract: sources of truth, evidence and proof requirements, ownership, working modes, the reviewed change loop, maintenance isolation, decision authority, dependency and fork rules, the 0.0.x to 0.1.0 release progression, and branch and publication rules. Add .agents/ with scope, implement, verify, maintenance and release procedures; reviewer, architecture debt scout, simplicity and refactoring roles; skills for the compositor, Servo rendering, runtime capabilities, appd sessions, packages and data, Linux deployment, integration verification and documentation; and verify.py, which runs the existing check profiles with --locked from any directory, stops on the first failure and supports --dry-run. check_toolkit.py validates local links and heading anchors, metadata, catalog coverage and issue forms. A new contributor-toolkit CI job runs both. The structure follows the Resina Design System toolkit at 1e768064f57a1e403ab271822383e732795905a6, adapted to WEFT. Validation, against the committed lockfiles: - verify.py toolkit: checker passes, 28 runner/checker tests pass - verify.py portable, demos, packages: pass - verify.py linux, runtime, servo-embed: fail on existing defects (clippy collapsible_if in the winit backend, three clippy lints in weft-runtime with wasmtime-runtime, and an E0308 in the selected Servo revision's servo-layout); the runner reports the failing status Add CONTRIBUTING.md, issue forms for defects and changes, maintenance problems and decisions of direction, and a pull request template asking for ownership, proof and the validation actually performed. README.md links the contribution guide.
2026-10-08 23:40:08 +00:00
- `contributor-toolkit` — links, metadata and catalog of the contributor toolkit, and runner tests
## Security
See `docs/security.md`. Key points:
- Capabilities declared in `wapp.toml`, validated at install, enforced at runtime
- Per-app OS processes with systemd cgroup limits
- WASI filesystem isolation via preopened directories
- Ed25519 package signing; optional EROFS dm-verity
- Optional seccomp BPF blocklist in `weft-runtime`
- SpiderMonkey is not sandbox-isolated beyond process-level isolation (see `docs/security.md`)
## Servo fork
- Repository: `https://github.com/marcoallegretti/servo`, branch `servo-weft`
- Base revision: `04ca254f`
- Patches: keyboard input, backdrop-filter in stylo
- See `crates/weft-servo-shell/SERVO_PIN.md` for Servo integration status and known limitations
docs: add engineering contract, contributor toolkit and templates Add AGENTS.md as the single engineering contract: sources of truth, evidence and proof requirements, ownership, working modes, the reviewed change loop, maintenance isolation, decision authority, dependency and fork rules, the 0.0.x to 0.1.0 release progression, and branch and publication rules. Add .agents/ with scope, implement, verify, maintenance and release procedures; reviewer, architecture debt scout, simplicity and refactoring roles; skills for the compositor, Servo rendering, runtime capabilities, appd sessions, packages and data, Linux deployment, integration verification and documentation; and verify.py, which runs the existing check profiles with --locked from any directory, stops on the first failure and supports --dry-run. check_toolkit.py validates local links and heading anchors, metadata, catalog coverage and issue forms. A new contributor-toolkit CI job runs both. The structure follows the Resina Design System toolkit at 1e768064f57a1e403ab271822383e732795905a6, adapted to WEFT. Validation, against the committed lockfiles: - verify.py toolkit: checker passes, 28 runner/checker tests pass - verify.py portable, demos, packages: pass - verify.py linux, runtime, servo-embed: fail on existing defects (clippy collapsible_if in the winit backend, three clippy lints in weft-runtime with wasmtime-runtime, and an E0308 in the selected Servo revision's servo-layout); the runner reports the failing status Add CONTRIBUTING.md, issue forms for defects and changes, maintenance problems and decisions of direction, and a pull request template asking for ownership, proof and the validation actually performed. README.md links the contribution guide.
2026-10-08 23:40:08 +00:00
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md). [AGENTS.md](AGENTS.md) is the engineering contract and [BLUEPRINT.md](BLUEPRINT.md) the accepted direction toward `0.1.0`.