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.
C cdebiandesktop-environmentebpffirewalllandlocklinuxlinux-distributionopen-sourceprivacyquickjsraspberry-pi-5reactsecuritywaylandwayland-compositor
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.mdindex 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 belowof 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-19diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 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 failsto 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.mdindex 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 (seediff --git a/docs/RELEASING.md b/docs/RELEASING.mdindex 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 documentedAlso 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 writesdiff --git a/docs/SIGNING.md b/docs/SIGNING.mdindex 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`).++| | |+|---|---|+|  |  |+| One byte changed in the default theme: the classic theme loads and says so | Every theme modified: the recovery screen |+|  |  |+| About: System app, Verified | About: Development build |+|  | |+| 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 → 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.mdindex 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 slowIf keys show up late in one app (for example Chromium) but not in LordOS's own apps (Notes, thediff --git a/docs/system-apps-about-dev-light.png b/docs/system-apps-about-dev-light.pngnew file mode 100644index 0000000..f990d9eBinary files /dev/null and b/docs/system-apps-about-dev-light.png differdiff --git a/docs/system-apps-about-verified-dark.png b/docs/system-apps-about-verified-dark.pngnew file mode 100644index 0000000..0b0916eBinary files /dev/null and b/docs/system-apps-about-verified-dark.png differdiff --git a/docs/system-apps-app-recovery.png b/docs/system-apps-app-recovery.pngnew file mode 100644index 0000000..0b6ce9fBinary files /dev/null and b/docs/system-apps-app-recovery.png differdiff --git a/docs/system-apps-modified.png b/docs/system-apps-modified.pngnew file mode 100644index 0000000..e34a70dBinary files /dev/null and b/docs/system-apps-modified.png differdiff --git a/docs/system-apps-recovery.png b/docs/system-apps-recovery.pngnew file mode 100644index 0000000..a7355f3Binary files /dev/null and b/docs/system-apps-recovery.png differdiff --git a/docs/system-apps-store-dark.png b/docs/system-apps-store-dark.pngnew file mode 100644index 0000000..d7a5e15Binary files /dev/null and b/docs/system-apps-store-dark.png differdiff --git a/docs/system-apps-store-light.png b/docs/system-apps-store-light.pngnew file mode 100644index 0000000..ab302c9Binary files /dev/null and b/docs/system-apps-store-light.png differ