Skip to content

LordOS — a free, fast and secure GNU/Linux distribution based on Debian, with its own desktop environment: display server and Wayland compositor in C, a React UI engine on QuickJS, and private native apps.

Docs: describe exactly what the firewall restrictions enforce, and correct overstated claims

Federico Pereira2075116d3e79
diff --git a/README.md b/README.md
index d8dc8d0..92437f3 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,8 @@
LordOS is a free GNU/Linux distribution based on Debian 13. It ships its own desktop
environment instead of GNOME or KDE, built from its fundamental components on top of Debian and
Wayland, and it doesn't use X11: a display server and Wayland compositor written in C, its own React-based UI engine, and native apps designed to feel calm,
-clear and private. An idle session uses about 120 MB of RAM. Its look and workflow take inspiration from the desktop of a well-known
+clear and private. Measured idle, the whole system uses 465–487 MB of RAM, of which `lord-server`
+(the display server with the whole desktop) is 32–36 MB. Its look and workflow take inspiration from the desktop of a well-known
fruit-logo company: a Dock, an app launcher, a menu bar, instant search and polished native
apps, all reimagined as free software. It runs on Intel/AMD PCs and on the Raspberry Pi 5, and
it still runs regular Linux apps such as Chromium, Firefox, GTK and Qt programs.
@@ -22,16 +23,19 @@ it still runs regular Linux apps such as Chromium, Firefox, GTK and Qt programs.
1. **Our own, end to end.** Display server, Wayland compositor and UI engine; login, sessions
and remote desktop; app store and package installer; firewall; password manager; touchpad
driver. All written for LordOS.
-2. **Light and smooth.** Built for modest hardware: about 120 MB at rest and 0 % CPU when idle,
+2. **Light and smooth.** Built for modest hardware: the whole system idles at 465–487 MB of RAM
+ (`lord-server` 32–36 MB) and about 1 % CPU (see `docs/ISO.md`, "Final ISO test", and
+ `docs/RASPBERRY.md`),
windows that move at the display's refresh rate, GPU composition when available and a CPU
path when not.
3. **Secure by design.**
- Third-party apps run sandboxed in their own process and ask before using the camera,
microphone, files or network.
- - Every app gets kernel-enforced network rules (allow, block, LAN-only, per domain).
+ - Per-app network rules enforced by the kernel (allow, block, LAN only), with per-domain
+ rules coming, and restrictions for LordOS apps (camera, microphone, screen, files and more).
- A built-in Monitor shows network and hardware activity per app, with a world map.
- Signed packages, capture-protected windows and an encrypted password vault.
-4. **Complete and polished.** More than 35 native apps (Files, Mail, Calendar, Contacts,
+4. **Complete and polished.** 29 native apps (Files, Mail, Calendar, Contacts,
Photos, Player, PDF viewer, Passwords, Disks, Backups and more), multiple monitors with
sharp fractional scaling, touchpad gestures, multi-user sessions, remote desktop from any
browser, and English, Spanish and Portuguese, including right-to-left scripts.
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index fcd42fa..c9939e9 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -14,13 +14,13 @@ like React Native but on top of our display server.
│ <View style={{flexDirection:'row', borderRadius:12}}>
▼
lord-ui (C, ours) ───── QuickJS (JS engine, vendored)
- │ + our own React reconciler + our own flexbox layout
+ │ + a host config for the stock react-reconciler + our own flexbox layout
│ + our own 2D rasterizer + text (stb_truetype)
▼
lord-server (C, ours) display server: DRM/KMS + evdev, windows, focus,
│ composition, theme decorations
│ + Wayland protocol → GTK (GNOME), Qt (KDE) apps,
- │ Firefox, Electron; optional Xwayland for X11
+ │ Firefox, Electron (Wayland only: Xwayland is not supported)
▼
Linux kernel (minimal Debian 13, generic kernel with DRM)
```
@@ -29,7 +29,7 @@ like React Native but on top of our display server.
|---------------|-------------|---------------------------------------------------------------|
| `server/src/` (kms, input, canvas) | **M1 done** | Display (KMS), input (evdev), 2D rasterizer |
| `server/src/ui/` | **M2 done** | Nodes, styles, flexbox, text, images, painting, damage, QuickJS |
-| `runtime/` | **M2 done** | React renderer (`@lordos/runtime`): reconciler, CSS → native, events |
+| `runtime/` | **M2 done** | React renderer (`@lordos/runtime`): a host config for the stock `react-reconciler` package, CSS → native, events |
| `themes/default/` | **M2 done** | Theme with a menu bar, a dock and an app launcher, with our own assets |
| `server/src/ui/js_sys.c` | **M3 done** | System APIs: fs (in `$HOME`), /proc, settings, themes, session |
| `sdk/` | **M3 done** | `@lordos/sdk`: windows, settings, tokens, controls, system hooks |
diff --git a/docs/FIREWALL.md b/docs/FIREWALL.md
index 492dd45..ea79d94 100644
--- a/docs/FIREWALL.md
+++ b/docs/FIREWALL.md
@@ -82,26 +82,74 @@ A valid id:
- **Trusted apps:** nothing is recorded and nothing is asked for them. Explicit rules still
apply: a `deny` the owner set for a trusted app is enforced.
-- **Restricted apps:** each one has a set of restrictions.
-
- | Restriction | In the JSON | Who enforces it |
- |---|---|---|
- | no internet | `no-internet` | `fw_decide` |
- | no LAN | `no-lan` | `fw_decide` (also `127.0.0.1` and `::1`) |
- | no network | `no-network` | `fw_decide` |
- | no incoming connections | `no-incoming` | `fw_decide` |
- | no camera | `no-camera` | whoever hands out the camera (`fw_blocks`) |
- | no microphone | `no-mic` | same |
- | no screen capture | `no-screen` | same |
- | no USB | `no-usb` | same |
- | no Bluetooth | `no-bluetooth` | same |
- | no files outside the picker | `no-files` | same |
- | no notifications | `no-notifications` | same |
+- **Restricted apps:** each one has a set of restrictions. The four network ones are decided by
+ `fw_decide` and enforced in the kernel by `lord-netperm` for every app with its own scope. The
+ others are enforced where the resource is handed out (see
+ [Non-network restrictions](#non-network-restrictions)).
+
+ | Restriction | In the JSON | .lpk apps and Passwords (`lpk:<id>`) | Built-in apps (`lordos`) | Linux apps (`desktop:<id>`) |
+ |---|---|---|---|---|
+ | no internet | `no-internet` | `lord-netperm` | `lord-netperm` | `lord-netperm` |
+ | no LAN | `no-lan` | same (also `127.0.0.1` and `::1`) | same | same |
+ | no network | `no-network` | same | same | same |
+ | no incoming connections | `no-incoming` | same | same | same |
+ | no camera | `no-camera` | broker (`brokercam.c`) | `js_media.c` | not yet |
+ | no microphone | `no-mic` | broker (`BOP_MIC`, camera videos) | `js_media.c` | not yet |
+ | no screen capture | `no-screen` | broker (the `screen` permission; isolated apps have no capture API) | `js_media.c` | not yet |
+ | no USB | `no-usb` | broker (`BOP_VAULT_FIDO`, the `usb` permission) | not offered (the desktop itself) | not yet |
+ | no Bluetooth | `no-bluetooth` | broker (the `bluetooth` permission; no Bluetooth API in app mode) | not offered (the desktop itself) | not yet |
+ | no access to your files | `no-files` | broker (file picker, camera saves, the `files` permission) | not offered (the desktop itself) | not yet |
+ | no reading the clipboard | `no-clipboard` | broker (`BOP_CLIP_GET`, the `clipboard` permission) | not offered (the desktop itself) | not yet |
+ | no notifications | `no-notifications` | `sdk/notify.js` and the `notifications` permission | `sdk/notify.js` | not yet |
An app is in only one list: trusting it removes it from the restricted ones, and restricting it
-removes the trust. Non-network restrictions are queried with `fw_blocks(app, flag)`. They beat a
-per-app permission granted in `permisos.json`: a restricted app with no camera doesn't get it even if
-it was given once.
+removes the trust. Non-network restrictions are queried with `fw_blocks(app, flag)`, through
+`server/src/sec/restrict.h`. They beat a per-app permission granted in `permisos.json`: a
+restricted app with no camera doesn't get it even if it was given once.
+
+### Non-network restrictions
+
+`lord.fw` (`ui/js_fw.c`) owns the rule store; `restrict_set_store()` hands the same store to
+`sec/restrict.c`, so a change made in Settings applies to the next request at once, without
+reloading anything. What each kind of app goes through:
+
+- **Isolated apps (`.lpk` and Passwords, firewall id `lpk:<id>`).** Everything they get from the
+ user goes through the broker, so the broker is the enforcement point (`brokersrv.c`,
+ `brokercam.c`). `restrict_perm_pkg()` returns `PERM_DENY` when a restriction covers a
+ permission, whatever `permisos.json` says. A restricted request is refused without drawing a
+ prompt, and the reply carries a code line (`fw.restricted.camera app=<id>`), which the app side
+ throws as a translated error (`errors.json`):
+ - `BOP_PERM` answers `"0 fw.restricted.<perm> …"` for camera, microphone, screen, USB,
+ Bluetooth, files, clipboard and notifications;
+ - `BOP_CAMERA`: `list` returns no cameras, `open` is refused, and photo or video saves (they are
+ user files) are refused under `no-files`;
+ - `BOP_MIC`, `BOP_PICK` (the file picker), `BOP_CLIP_GET` (reading the clipboard) and
+ `BOP_VAULT_FIDO` (the USB security key of Passwords) are refused;
+ - `BOP_DEVICE` does not light the indicator for a restricted device;
+ - a prompt the user allows, or a file the user picks, after the app was restricted is refused too.
+- **Built-in apps inside `lord-server` (firewall id `lordos`).** They share one JS context with
+ the desktop shell, so the checks are at the native boundary that knows what is asked for:
+ `js_media.c` `permitted()` refuses camera, microphone and screen capture and recording with
+ `fw.restricted.*`, before the permission. `sdk/notify.js` drops notifications from built-in and
+ isolated apps (`lord.fw.blocks()`); Settings' own system warnings (battery) are exempt. The
+ `LordOS` row in Settings does not offer files, USB, clipboard or Bluetooth: that row is the
+ desktop itself (Files, copy and paste, Disks, Settings → Bluetooth), and the screen says so in
+ one line. Restrict individual apps instead.
+- **Linux apps (`desktop:<id>`) and terminal programs.** They are not sandboxed and reach devices
+ directly, so today only the network restrictions apply to them. Kernel-level checks for them
+ are separate work.
+
+**Live revocation.** Adding a restriction to a running app (`restrict_changed()`, called by
+`setRestricted`) takes the device away at once, the same way revoking the permission does: for an
+isolated app `brokersrv_revoke()` sends `revoke`, kills the camera's `lord-media`, closes the
+microphone stream and stops a camera video that records sound; for the built-in apps a hook in
+`js_media.c` kills the camera helper (the window gets `closed` with `revoked`) and finishes
+microphone and screen recordings properly. New notifications and file picks are refused from that
+moment.
+
+Tested by `server/tests/broker_restrict_test.c` (`make -C server test`): the real broker code
+against a fake app, every restriction with and without it, no prompt, the error codes, live
+revocation of camera and microphone and the built-in apps' hook.
### Precedence
@@ -540,6 +588,7 @@ the SDK calls once per second while the Monitor's Network tab is open.
| `setTrusted(app, on)`, `setRestricted(app, [restriction])`, `setMode('silent'\|'ask'\|'off')` | lists and mode |
| `rules(app)`, `addRule({ app, dir, dst, port, proto, action })`, `removeRule(id)` | rules (domains, networks, ports) |
| `poll()` | `{ counts, events }` |
+| `blocks(app, restriction)` | `true` if the app is restricted in it (`sdk/notify.js`) |
Everything is validated in C:
@@ -710,8 +759,9 @@ What remains of steps 3 and 4 (the original design; what's done is above, in "`l
- **Restricted apps:** `fw_set_restricted`, with a checkbox per restriction from the table
above.
- **The mode selector:** silent / ask / off.
-- **Outside the network:** the non-network restrictions are queried with `fw_blocks` by the
- permission broker (`server/src/sec/brokersrv.c`, for camera, microphone, screen, USB, Bluetooth
- and notifications) and by the file picker (`no-files`). They are queried before `perms.c`.
+- **Outside the network:** the non-network restrictions are queried with `fw_blocks` (through
+ `sec/restrict.h`) before `perms.c`, by the broker for isolated apps and by `js_media.c` and
+ `sdk/notify.js` for the built-in apps. Exactly what is enforced where is in
+ [Non-network restrictions](#non-network-restrictions).
- **The JS API:** goes in its own `js_fw.c`, with input validation like the rest of `lord.*`. It
never takes paths: the file's path is fixed by the server.
diff --git a/docs/LORDOS-BRAND.md b/docs/LORDOS-BRAND.md
index 16c19ee..719b443 100644
--- a/docs/LORDOS-BRAND.md
+++ b/docs/LORDOS-BRAND.md
@@ -16,8 +16,8 @@ the renders by hand.
LordOS is a free, fast and secure GNU/Linux distribution based on Debian, with a desktop environment of
its own, built from its fundamental components on top of Debian and Wayland. It has its own display server and Wayland compositor written in C and
-its own React-based interface engine, an idle session uses
-about 120 MB of RAM, and it brings a Dock, an app launcher, a menu bar, instant search and polished
+its own React-based interface engine, the whole system idles at 465–487 MB of RAM
+(`lord-server` 32–36 MB), and it brings a Dock, an app launcher, a menu bar, instant search and polished
native apps to PCs and to the Raspberry Pi 5, while still running regular Linux applications. The
crown stands for a desktop where the user rules: fast, private and fully under their control.
diff --git a/docs/MONITOR.md b/docs/MONITOR.md
index 83ec8ac..4a68f29 100644
--- a/docs/MONITOR.md
+++ b/docs/MONITOR.md
@@ -28,8 +28,8 @@ itself.
- **Left:** search (by app, address or country) and one row per app with its icon, number of
connections, a traffic bar (received in green, sent in orange, relative to the app that moved
- the most), the bytes and the **Rule** column, reserved for the firewall: today it is a read-only
- switch set to "allow". Each app expands to show its destinations (IP and country). At the bottom,
+ the most), the bytes and the **Rule** column: a per-app allow/deny switch that `lord-netperm`
+ enforces in the kernel (see "Phase 2"). Each app expands to show its destinations (IP and country). At the bottom,
the current download and upload speed and per-second bars for the last 60 s.
- **Center:** the map fills the whole height of the column. It has an arc from "This computer" to
each country, one dot per country (bigger the more connections) and pill labels with the name
diff --git a/docs/PRIVACY.md b/docs/PRIVACY.md
index c21bbb8..d30f4eb 100644
--- a/docs/PRIVACY.md
+++ b/docs/PRIVACY.md
@@ -27,6 +27,20 @@ first time and the user decides. See also [SIGNING.md](SIGNING.md) (signed packa
| Camera as decoded frames through a ring (via lord-media), after consent | **done**, tested on VM 122 with v4l2loopback (see [Camera for isolated apps](#camera-for-isolated-apps)) |
| Several windows per isolated app | **done**, tested on VM 122 (see [Several windows per isolated app](#several-windows-per-isolated-app)) |
+## What is isolated today
+
+Not every program on LordOS is sandboxed. This is exactly what applies to each kind:
+
+| Kind | Process | Landlock + seccomp | cgroup scope | Broker and permissions | Firewall |
+|---|---|---|---|---|---|
+| `.lpk` apps and Passwords | own process (`lord-server --app <id>`) | yes | own (`app-lordos-lpk-<id>.scope`) | yes: every call is checked in `lord-server` | per app (`lpk:<id>`): network rules and every non-network restriction (broker) |
+| Other built-in apps | inside `lord-server` | no | `lord-server`'s | no broker: camera, microphone and screen are checked in C (`js_media.c`), notifications in `sdk/notify.js` | as "LordOS" (`lordos`): network rules; camera, microphone, screen and notifications restrictions |
+| Linux apps from the launcher | own process | no | own (`app-lordos-<id>.scope`) | no | per app (`desktop:<id>`): network rules (the non-network restrictions don't apply to them yet) |
+| Terminal programs | children of the Terminal's shell | no | `lord-server`'s | no | as "LordOS" (`lordos`): network rules |
+
+Flatpak, bubblewrap and namespaces are not used. The firewall's restrictions and where each one
+is enforced are in [FIREWALL.md](FIREWALL.md#non-network-restrictions).
+
## The per-app process
When a `.lpk` app is opened (app launcher, Dock, Store), `lord-server` launches it as its own
@@ -310,8 +324,15 @@ development) the apps run without a scope, with a warning.
- **Manifest:** an app declares `permissions`. The installer and the Store show them, and an app
can't obtain a permission it didn't declare (for example, `network` is only granted if it is
declared **and** allowed).
-- **Revoking** in Settings → Privacy applies to the next request; a permission already in use (for
- example, an open microphone) lasts until the app releases it or closes.
+- **Revoking** in Settings → Privacy applies at once to the camera and the microphone: the app is
+ told (`revoke`), `lord-server` kills the camera's `lord-media` and closes the microphone stream,
+ and a camera video that records sound stops (see [Menus and revocation](#menus-and-revocation)).
+ Other permissions apply to the next request. The network permission is applied when the app
+ starts (its scope's rules), so a change reaches a running app the next time it is opened.
+- **Firewall restrictions** (Settings → Privacy → App network access) are stronger than any
+ permission: a restricted app is refused without a prompt even if it was allowed before, and
+ restricting a running app takes its camera and microphone away at once, like revoking. See
+ [FIREWALL.md](FIREWALL.md#non-network-restrictions).
Permissions: `files`, `clipboard`, `notifications`, `network`, `camera`, `microphone`, `screen`,
`listen`, `usb`, `bluetooth`, `apps`.
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 6e49a82..213ebe2 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -203,8 +203,9 @@ our own installer, and network, VPN, sound and clipboard with our own interface.
`lordos-session-<uid>`; tested with fast user switching and remote desktop.
- [x] `sandbox_apply_helper` hardened for lord-media and lord-doc (no sockets or exec, threads
only, TSYNC, folders by fd, ioctl by class, our own kcmp): `sandbox-test helper` 17/17.
- - [ ] Pending: graphical powerbox (a dialog that hands over the fd), the camera fd and PipeWire
- stream to the app, live tokens/language/RTL and menus for the isolated app.
+ - [x] Graphical powerbox (a dialog drawn by `lord-server` that hands over only the fd), the
+ camera as a read-only frame ring and the microphone stream for the app, live
+ tokens/language/RTL and menus for the isolated app (`PRIVACY.md`).
- [x] **Per-app firewall**, steps 1 to 4 (`FIREWALL.md`), tested on VM 122:
- [x] rule store, precedence, `dnsmap` and JSON (`server/src/fw`, step 1);
- [x] `lord-netperm`, the root service that enforces the rules with cgroup BPF (connect, sendmsg,
@@ -213,8 +214,12 @@ our own installer, and network, VPN, sound and clipboard with our own interface.
0 differences) and names only from the system resolver (systemd-resolved monitor);
- [x] kernel test `tests/netperm_integration.sh` 18/18: deny/allow, "only
example.com", LAN only, no incoming, no network, off;
- - [x] Monitor: per-app Rule switch and allowed/denied counters; Settings →
- Privacy: mode, Trusted apps and Restricted apps;
+ - [x] Monitor: the Rule column is a per-app switch (`lord.fw.setAppRule`, enforced in the
+ kernel) with allowed/denied counters (`MONITOR.md`, "Phase 2"); Settings → Privacy: mode,
+ Trusted apps and Restricted apps;
+ - [x] non-network restrictions (camera, microphone, screen, USB, files, clipboard, Bluetooth,
+ notifications) enforced for LordOS apps in the broker, `js_media.c` and `sdk/notify.js`, with
+ live revocation (`FIREWALL.md`, "Non-network restrictions"); Linux apps: network only;
- [x] root-owned scopes: `lord-sessiond` places every app process and a Linux app can't move
itself to another cgroup (VM 122). Still open: `systemd-run --user --scope` (PID 1 moves it
into `user@<uid>.service`).
@@ -421,7 +426,8 @@ Details in `PASSWORDS.md`. Tested on VM 116 with a real `lord-sessiond` session
(`vc_attach_app`), files through the powerbox, FIDO2 and secret clipboard through the broker
(`BOP_VAULT_FIDO`, `BOP_CLIP_SECRET`), protected Wayland window. Revealed values never enter
`lord-server`'s JavaScript heap. In-process fallback kept (see `PASSWORDS.md`).
-- [ ] Keyring for isolated `.lpk` apps: a broker op that sets the owner from the verified app id.
+- [x] Keyring for isolated `.lpk` apps: a broker op (`BOP_KEYRING`, `sec/brokerkr.c`) that sets
+ the owner from the verified app id (`PASSWORDS.md`, "Keyring for isolated .lpk apps").
- [ ] Test with real FIDO2 keys (only the uhid software authenticator was available).
## M9 — Settings: hardware pages ✅ (2026-10-18)