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: verified system code and system apps (SIGNING, RELEASING, ARCHITECTURE, NATIVE-APPS, TROUBLESHOOTING), screenshots, CHANGELOG 0.8.2

Federico Pereirabeecab58c743
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d5e2d3d..c77f291 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,43 @@ suffix (`-beta`) and are published on GitHub as pre-releases. Each section below
of the matching [GitHub release](https://github.com/lordbasex/LordOS/releases), generated by
`tools/release/release-notes.sh` (see [docs/RELEASING.md](docs/RELEASING.md)).
+## [0.8.2] - Unreleased
+
+### Security
+
+- **LordOS checks its own code before running it.** Every bundle LordOS runs as its own code — the
+ themes with the shell and every native app, the login screen, the app host of isolated apps and
+ the system apps that run as their own process — is listed with its SHA-256 in
+ `/usr/lib/lordos/code-manifest.json`, signed with the LordOS release key (Ed25519).
+ lord-server verifies the signature with the public key compiled in, and the hash of each bundle
+ as it loads it, from the same read (no window to swap the file). A bundle that doesn't match is
+ not run: the desktop falls back to another theme and shows "This LordOS component was modified and
+ was not loaded"; with nothing left to load (or at the login screen) a built-in recovery screen
+ explains it and how to repair it, never a blank screen. It protects against changes by non-root
+ processes and offline modification; root can still replace lord-server itself, which phase 3
+ (fs-verity, A/B images) will cover. Cost on a session start: about 7 ms on a Raspberry Pi 5,
+ 18–34 ms on a 1.8 GHz Xeon VM
+ ([docs/SIGNING.md](docs/SIGNING.md#verified-system-code-082)).
+- **System apps can't be removed.** Store → Installed shows "System app — part of LordOS" instead
+ of Remove for the apps that come with LordOS, and the `lordos` package is marked `Protected` so the
+ Store's package engine refuses to remove it.
+
+### Added
+
+- About LordOS shows a "System app" badge and the state of the system code: "Verified", or
+ "Development build" for an unsigned development tree.
+- `lord-server --check-code [<folder>]` checks a whole installed tree against the signed manifest
+ (troubleshooting, and the `.deb` build).
+- SHA-256 uses the CPU's SHA-256 instructions on the Raspberry Pi 5 (5× faster there), and the
+ portable code is about twice as fast.
+
+### Changed
+
+- Releases: `tools/release/sign-code.sh` signs the system-code manifest on the maintainer's machine
+ before the build; `make -C server RELEASE=1` builds a lord-server that only runs signed code, and
+ `tools/iso/mkdeb.sh` refuses to package bundles that don't match
+ ([docs/RELEASING.md](docs/RELEASING.md)).
+
## [Unreleased]
## [0.8.1-beta] - 2026-10-19
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index c9939e9..19cde7b 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -247,6 +247,10 @@ other bundle; settings persist on disk.
- `lord.settings` only writes `~/.config/lordos/settings.json` (max. 64 KB, atomic write).
- `lord.themes.use` only accepts plain folder names in `themes/`; a theme that fails
to load is banned to avoid loops.
+- LordOS's own JavaScript (themes, login screen, app host, system apps) only runs if it matches
+ `code-manifest.json`, signed with the release key and checked by lord-server at load time from the
+ same read that is evaluated (`server/src/sec/codesig.c`, `SIGNING.md`, "Verified system code").
+ A modified bundle is not run: another theme, or the built-in recovery screen.
- There is no API to run arbitrary commands. The only way to start a process is
`lord.term.create()`, which launches the user's own login shell (the one in `/etc/passwd`)
with no capabilities and no `SUDO_*` variables, just like any terminal emulator.
diff --git a/docs/NATIVE-APPS.md b/docs/NATIVE-APPS.md
index fb82473..72be0ec 100644
--- a/docs/NATIVE-APPS.md
+++ b/docs/NATIVE-APPS.md
@@ -93,6 +93,14 @@ The full example is in `examples/apps/fractal/`. It uses:
The rest of the SDK is the same as for the bundled apps (see `apps/README.md`).
+## System apps (0.8.2)
+
+The apps in `apps/` are **system apps**: they are built into the theme bundles, which LordOS checks
+against its signed manifest before running them (see [SIGNING.md](SIGNING.md), "Verified system
+code"), and the Store never offers to remove them ("System app — part of LordOS"). An installed
+`.lpk` is never a system app, even with the same id: the theme's app wins and the package is not
+listed. `isSystemApp(id)` from `@lordos/sdk` tells them apart.
+
## Permissions and trust (M8)
Since M8 there is **package signing** and a **permissions and isolation** model (see
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
index 9234c22..93ed773 100644
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -43,10 +43,23 @@ The releases page is the project's public changelog: every release is documented
Also bump `package.json` (`version`, `lordos.channel`) and commit both.
2. **Tag.** `git tag -a v<version> -m "LordOS <version>"` on that commit, and push the tag.
-3. **Build** from the tag: the ISO on the build VM (`tools/iso/build.sh`, [ISO.md](ISO.md)), the
- Raspberry Pi 5 image (`tools/rpi/build-img.sh`, [RASPBERRY.md](RASPBERRY.md)) and the `.deb`
- for amd64 and arm64. Copy them, and `tools/install/install.sh` as `install.sh`, into one release
- folder.
+3. **Sign the system code, then build** from the tag.
+ - On the maintainer's machine (where the release key lives): `npm run build`, then
+ `tools/release/sign-code.sh`. It regenerates `code-manifest.json` (the SHA-256 of every theme
+ bundle, the app host and the system apps) and writes `code-manifest.sig` with the release key,
+ checked against `tools/release/lordos-release.pub.pem` ([SIGNING.md](SIGNING.md), "Verified system
+ code"). The bundles are the same for every architecture: one signature serves all the images.
+ - Send the tree, with both files, to the build VMs (never the key). Build lord-server as a release:
+ `make -C server RELEASE=1` (it only runs code signed with the release key, with no development
+ mode).
+ - Build the ISO on the build VM (`sudo REQUIRE_SIGNED_CODE=1 tools/iso/build.sh`, [ISO.md](ISO.md)),
+ the Raspberry Pi 5 image (`sudo RELEASE=1 REQUIRE_SIGNED_CODE=1 tools/rpi/build-img.sh`,
+ [RASPBERRY.md](RASPBERRY.md)) and the `.deb` for amd64 and arm64
+ (`REQUIRE_SIGNED_CODE=1 tools/iso/mkdeb.sh`). `mkdeb.sh` puts `code-manifest.json` and
+ `code-manifest.sig` in `/usr/lib/lordos/` and runs `lord-server --check-code` on the staged tree:
+ the package is not built if a bundle changed after signing or the signature is missing. A bundle
+ rebuilt after signing means signing again.
+ - Copy them, and `tools/install/install.sh` as `install.sh`, into one release folder.
4. **SBOM.** On each build VM, `tools/release/make-sbom.sh lordos_<v>_<arch>.deb`, and put the
`.spdx.json` files in the release folder ([COMPLIANCE.md](COMPLIANCE.md)).
5. **Sign.** On the maintainer's machine, `tools/release/sign-release.sh <release-dir>`: it writes
diff --git a/docs/SIGNING.md b/docs/SIGNING.md
index 1d50cb5..924d0ac 100644
--- a/docs/SIGNING.md
+++ b/docs/SIGNING.md
@@ -153,6 +153,178 @@ its signature cover it too. See [COMPLIANCE.md](COMPLIANCE.md).
The whole release process (changelog, tag, build, SBOM, signing and `gh release create`) is in
[RELEASING.md](RELEASING.md).
+## Verified system code (0.8.2)
+
+The `.lpk` signing above covers apps installed by the user. LordOS's **own** code — the desktop,
+the login screen and every native app — is checked too: lord-server refuses to run a bundle that no
+longer matches the signed copy. This is phase 1 of 3 of "System apps immutable" (phase 3 brings
+fs-verity and A/B system images).
+
+### What is signed
+
+`code-manifest.json`, at the root of the LordOS folder (`/usr/lib/lordos`; the repository root in a
+development tree), lists the size and SHA-256 of every file LordOS runs as JavaScript:
+
+| File | What it is |
+|---|---|
+| `themes/<theme>/theme.bundle.js` | the shell, the SDK, the React runtime and **every native app** (they are bundled into each theme), for `default`, `classic` and `greeter` (the login screen) |
+| `assets/app-host.bundle.js` | React + SDK of isolated app processes (`lord-server --app <id>`) |
+| `assets/sysapps/<id>/app.js` | system apps that run as their own sandboxed process (Passwords) |
+
+```json
+{
+ "format": 1,
+ "kind": "lordos-system-code",
+ "version": "0.8.2",
+ "files": [
+ { "path": "assets/app-host.bundle.js", "size": 433360, "sha256": "25d0b1ae…" },
+ { "path": "themes/default/theme.bundle.js", "size": 1492265, "sha256": "f9546e6e…" }
+ ]
+}
+```
+
+`code-manifest.sig` is the base64 of the Ed25519 signature over the exact bytes of the manifest,
+made with the **LordOS release key** (the same key as `SHA256SUMS.sig`, see "Release files" below).
+The public key is compiled into lord-server (`codesig_release_key` in `server/src/sec/codesig.c`;
+`build/codesig-test` checks it against `tools/release/lordos-release.pub.pem`), so no file on disk
+can add a trusted key. The `kind` field keeps a signature made for another purpose from passing as
+this one.
+
+**Not listed, on purpose:** fonts, language catalogs, icons, images, Help articles, `theme.json`
+and a system app's `manifest.json` (its window size; its permissions are decided by lord-server).
+They are data read by bounded parsers, not code. A modified catalog can change what a text says
+but cannot run anything; phase 3 (fs-verity over the whole system image) covers them.
+
+`tools/code-manifest.mjs` writes the manifest (deterministic: the same bundles give the same bytes);
+`npm run build` runs it after building, and removes a `code-manifest.sig` that no longer matches.
+
+### How lord-server checks it (`server/src/sec/codesig.c`)
+
+- **Once per process**, before the first bundle: read `code-manifest.json` and `.sig` from the
+ LordOS folder, verify the signature with the compiled-in key, then parse the manifest with the
+ strict JSON reader (format 1, the right kind, relative paths without `.`/`..`, sorted and unique,
+ 64 lowercase hex digits, at most 4096 files and 1 MB). An isolated app's process does this before
+ its sandbox is applied.
+- **Per bundle, lazily, when it is loaded:** the file is opened under the LordOS folder with
+ `openat2(RESOLVE_BENEATH)` (no `..`, no link out of it), read whole from that one descriptor, and
+ the SHA-256 of **exactly those bytes** is compared with the manifest; the same buffer is what
+ QuickJS evaluates. Nothing is read twice, so there is no window to swap the file between the check
+ and the use (no TOCTOU). Only the bundle that is used is hashed: the login screen hashes the greeter
+ bundle, a session its theme, an isolated app the app host and its `app.js`.
+- The SHA-256 is our own (`server/src/pkg/crypto.c`): portable C, unrolled, and on aarch64 the CPU's
+ SHA-256 instructions when it has them (the Raspberry Pi 5; checked at run time, compared bit for bit
+ with the C code by `build/codesig-test`). x86-64 uses the C code (its SHA extensions are not used
+ until they are tested on such a CPU).
+
+### States
+
+| State | When | About shows |
+|---|---|---|
+| **Verified** | signed manifest, good signature, every loaded bundle matches | "Verified" (green) and "Signed by LordOS · N components" |
+| **Development build** | no `.sig` (a development tree, `npm run build`), or no manifest at all, in a development build of lord-server | "Development build" (orange) and "Development build: the system code is not signed by LordOS." |
+| **Modified** | a bundle does not match, or the manifest or its signature is bad | "Modified — not loaded" (red) |
+
+In a development build with an unsigned manifest the hashes are still checked, so a modified bundle
+is refused the same way. A **release build** (`make -C server RELEASE=1`) never accepts the
+development state: without a valid signature nothing is loaded.
+
+### When something does not match
+
+- The bundle is **not run**. The refusal is logged (`code: REFUSED themes/default/theme.bundle.js:
+ SHA-256 differs from the manifest — this LordOS component was modified and was not loaded` in the
+ session log or the journal) and remembered for the session.
+- **A theme:** lord-server falls back to the default theme, then the classic one, and the desktop
+ shows a notification: **"This LordOS component was modified and was not loaded"**, naming the file,
+ with a Details button (About). The broken theme is not offered again in this session.
+- **Nothing left to load** (every theme, the login screen, or a bad manifest/signature): the built-in
+ **recovery screen** — compiled into lord-server, so it is as trusted as lord-server itself — says
+ what happened, lists the files and how to repair it (`sudo apt install --reinstall lordos`); in a
+ session it has a Log Out button. Never a blank screen.
+- **An isolated system app** (Passwords): its window shows the same recovery screen instead of the app.
+
+`lord.code.status()` (`ui/js_sec.c`) gives the SDK the state and the refusals; `sdk/codesig.js`
+shows the notification. `lord-server --check-code [<folder>] [--require-signed]` checks a whole tree
+the way a session would and exits 1 if anything is off (used by `tools/iso/mkdeb.sh`, and for
+troubleshooting: `sudo /usr/lib/lordos/bin/lord-server --check-code`).
+
+| | |
+|---|---|
+| ![modified](system-apps-modified.png) | ![recovery](system-apps-recovery.png) |
+| One byte changed in the default theme: the classic theme loads and says so | Every theme modified: the recovery screen |
+| ![about verified](system-apps-about-verified-dark.png) | ![about development](system-apps-about-dev-light.png) |
+| About: System app, Verified | About: Development build |
+| ![app recovery](system-apps-app-recovery.png) | |
+| Passwords' `app.js` modified: its window explains it | |
+
+### System apps can't be removed
+
+Every app in `apps/` is a **system app** (`system: true`, set by `tools/build-theme.mjs`; a
+package can never claim it, `sdk/windows.js` `isSystemApp`). Store → Installed shows "System app —
+part of LordOS" where a Linux app has Remove, and About shows a "System app" badge. The `lordos`
+Debian package is marked `Protected: yes` (Debian's field for packages the system needs), so the
+Store's package engine refuses to remove it (`pkg.removeEssential`, the same rule as essential
+packages) and dpkg wants `--force-remove-protected`. This part was checked in the code
+(`status.c` reads the field into `IF_PROTECTED`, `resolve.c` refuses), not yet on an installed
+0.8.2 `.deb`.
+
+| | |
+|---|---|
+| ![store light](system-apps-store-light.png) | ![store dark](system-apps-store-dark.png) |
+| Store → Installed: system apps can't be removed | The same in dark mode |
+
+### Threat model
+
+- **Protects against** a process running as the user (or as any non-root account) changing
+ LordOS's code: it can't write `/usr/lib/lordos` anyway, and a copy elsewhere is never loaded
+ (lord-server only runs files under its own folder, checked against the signed list). It also
+ catches **offline modification** of the bundles or the manifest — a disk edited from another
+ system, a corrupted or tampered image — and plain corruption, and it tells the user instead of
+ running it.
+- **Does not protect against root.** An attacker with root can replace lord-server itself (and its
+ compiled-in key), or the kernel; no check inside lord-server can stop that. A development build of
+ lord-server accepts an unsigned manifest by design, so swapping in a development build also needs
+ root. Full protection of the system files against offline and root-level changes comes with phase 3
+ (fs-verity and A/B system images, verified from boot).
+- Fonts, catalogs and images are not covered (see above).
+
+### Startup cost
+
+Measured with the logs lord-server prints (`code: …`), 2026-10-19:
+
+| Machine | Signature check (once per process) | Default theme (1.46 MB) | Login screen (431 KB) | Added to a session start |
+|---|---|---|---|---|
+| VM 118 (Xeon Silver 4108, 1.8 GHz; C SHA-256, 118 MB/s) | 5.1 ms | 13–26 ms | 3.9 ms | **18–34 ms** |
+| Raspberry Pi 5 (Cortex-A76; SHA-256 instructions, 897 MB/s; C: 169 MB/s) | 5.3 ms | ≈1.6 ms | ≈0.5 ms | **≈7 ms** |
+
+On the Pi the hashing speed and the Ed25519 time come from `build/codesig-test` run on the board;
+the per-bundle figure follows from them. Evaluating the same theme takes 550–670 ms on the VM, so the
+check adds 2–5 %. Wall-clock time from start to "theme loaded" on the VM (5 runs each) was within
+noise of the build without the check (727–870 ms against 745–855 ms).
+
+### The release flow
+
+1. On the maintainer's machine: `npm run build`, then `tools/release/sign-code.sh` (regenerates
+ `code-manifest.json`, signs it with `~/.config/lordos-release/release-ed25519.key.pem` into
+ `code-manifest.sig` and verifies it against `lordos-release.pub.pem`). The bundles don't depend on
+ the architecture, so one signature serves amd64 and arm64.
+2. The tree (with both files) goes to the build VMs; `make -C server RELEASE=1`.
+3. `REQUIRE_SIGNED_CODE=1 tools/iso/mkdeb.sh` installs both files into `/usr/lib/lordos/` and runs
+ `lord-server --check-code` on the staged tree: the `.deb` is not built if a bundle doesn't match
+ or (release build) the signature is missing. The ISO and the Raspberry Pi image install that `.deb`
+ (`tools/rpi/build-img.sh` passes `RELEASE` and `REQUIRE_SIGNED_CODE` to its arm64 chroot).
+
+See [RELEASING.md](RELEASING.md), step 3.
+
+### Testing it (development)
+
+- `make -C server test` runs `build/codesig-test`: the parser, signatures (good, altered, other key,
+ bad encodings, wrong kind), one modified byte, truncation, unlisted files, a link out of the folder,
+ the development and release policies, the SHA-256 vectors on every path and the compiled-in key.
+- A **test build** can trust a throwaway key instead of the release key:
+ `make -C server CODE_PUBKEY=<64 hex digits>` (refused together with `RELEASE=1`), and
+ `CODE_PUB=test.pub.pem tools/release/sign-code.sh "$PWD" test.key.pem` signs with it. That is how the
+ "Verified" screenshots above were taken on VM 118; the release key was not used.
+
## Files
| Path | What it is |
@@ -165,3 +337,7 @@ The whole release process (changelog, tag, build, SBOM, signing and `gh release
| `server/src/ui/js_sec.c` | `lord.sign` for the SDK (status, restore, share, userKey) |
| `tools/lpk.mjs` | package, sign, verify, keygen and catalog |
| `packaging/keys/lordos-dev.pub` | development public key |
+| `server/src/sec/codesig.c` | verified system code: the signed manifest and the check of each bundle at load time |
+| `tools/code-manifest.mjs` | writes `code-manifest.json` (run by `npm run build`) |
+| `tools/release/sign-code.sh` | signs it with the release key (maintainer's machine only) |
+| `sdk/codesig.js` | the "component was modified" notification and `codeStatus()` for About |
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index b64e564..9eb2172 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -1,5 +1,22 @@
# Troubleshooting
+## "This LordOS component was modified and was not loaded"
+
+LordOS checks its own code (the themes, the login screen, the system apps) against a list signed with
+the LordOS key before running it ([SIGNING.md](SIGNING.md), "Verified system code"). This message,
+or the recovery screen, means a file in `/usr/lib/lordos` no longer matches: a disk error, an edit by
+hand, or tampering. To see which files:
+
+```sh
+sudo /usr/lib/lordos/bin/lord-server --check-code
+```
+
+To repair it, reinstall the package (your files and settings are not touched):
+
+```sh
+sudo apt install --reinstall lordos
+```
+
## Typing feels slow
If keys show up late in one app (for example Chromium) but not in LordOS's own apps (Notes, the
diff --git a/docs/system-apps-about-dev-light.png b/docs/system-apps-about-dev-light.png
new file mode 100644
index 0000000..f990d9e
Binary files /dev/null and b/docs/system-apps-about-dev-light.png differ
diff --git a/docs/system-apps-about-verified-dark.png b/docs/system-apps-about-verified-dark.png
new file mode 100644
index 0000000..0b0916e
Binary files /dev/null and b/docs/system-apps-about-verified-dark.png differ
diff --git a/docs/system-apps-app-recovery.png b/docs/system-apps-app-recovery.png
new file mode 100644
index 0000000..0b6ce9f
Binary files /dev/null and b/docs/system-apps-app-recovery.png differ
diff --git a/docs/system-apps-modified.png b/docs/system-apps-modified.png
new file mode 100644
index 0000000..e34a70d
Binary files /dev/null and b/docs/system-apps-modified.png differ
diff --git a/docs/system-apps-recovery.png b/docs/system-apps-recovery.png
new file mode 100644
index 0000000..a7355f3
Binary files /dev/null and b/docs/system-apps-recovery.png differ
diff --git a/docs/system-apps-store-dark.png b/docs/system-apps-store-dark.png
new file mode 100644
index 0000000..d7a5e15
Binary files /dev/null and b/docs/system-apps-store-dark.png differ
diff --git a/docs/system-apps-store-light.png b/docs/system-apps-store-light.png
new file mode 100644
index 0000000..ab302c9
Binary files /dev/null and b/docs/system-apps-store-light.png differ