diff --git a/.claude/settings.local.json b/.claude/settings.local.json deleted file mode 100644 index b36937b..0000000 --- a/.claude/settings.local.json +++ /dev/null @@ -1,29 +0,0 @@ -{ - "permissions": { - "allow": [ - "Read(//mnt/c/Code/MusallahBoard/**)", - "Bash(go build *)", - "Read(//mnt/c/**)", - "Bash(ls /mnt/)", - "PowerShell(wsl --status 2>&1 | Select-Object -First 5)", - "PowerShell(wsl --exec bash -c \"which go && go version\" 2>&1)", - "PowerShell(wsl --exec bash -c \"ls /usr/local/go/bin/go 2>/dev/null && echo found || echo not found; ls ~/go/bin/go 2>/dev/null && echo 'home found' || true\" 2>&1)", - "PowerShell(wsl --exec bash -c \"export PATH=`$PATH:/usr/local/go/bin && cd /mnt/c/Code/MusallahBoard/agent && mkdir -p build && CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags '-s -w -X github.com/LensBridge/agent/internal/version.Version=0.1.0-dev' -o build/musallahboard-agent-amd64 ./cmd/agent && echo 'Build OK' && ls -lh build/\" 2>&1)", - "Bash(wsl bash *)", - "PowerShell(go build *)", - "PowerShell(go test *)", - "Bash(ssh *)", - "Bash(bash -n packaging/lib/common.sh)", - "Bash(bash -n setup.sh)", - "Bash(bash -n setup-ubuntu.sh)", - "Bash(curl -s https://gitlab.com/buildroot.org/buildroot/-/raw/master/board/pc/grub.cfg)", - "Bash(curl -s https://gitlab.com/buildroot.org/buildroot/-/raw/master/board/pc/genimage-bios.cfg)", - "Bash(curl -s https://gitlab.com/buildroot.org/buildroot/-/raw/master/board/pc/post-image.sh)", - "Bash(chmod +x C:/Code/MusallahBoard/agent/buildroot-external/board/musallahboard/post-build.sh C:/Code/MusallahBoard/agent/buildroot-external/board/musallahboard/post-image.sh)", - "WebSearch", - "Read(//c/Code/MusallahBoard/**)", - "Read(//c/Code/**)", - "Read(//c/Code/MusallahBoard/update-anim/**)" - ] - } -} diff --git a/.gitattributes b/.gitattributes index 1c3d865..f24246a 100644 --- a/.gitattributes +++ b/.gitattributes @@ -4,9 +4,3 @@ *.toml text eol=lf *.go text eol=lf Makefile text eol=lf - -# Extensionless executables that run inside an initramfs. Without these, -# `* text=auto` hands a Windows checkout CRLF line endings and the kernel then -# looks for an interpreter literally named "/bin/sh\r" — in an environment with -# no useful error message and no way to log in and find out. -packaging/luks/* text eol=lf diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e1186d0..499123e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -26,7 +26,7 @@ jobs: cache-dependency-path: agent/go.sum - name: Regenerate the API client - working-directory: agent/internal/api + working-directory: agent/internal/online/api run: | go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@v2.8.0 \ -config oapi-codegen.yaml \ @@ -35,10 +35,10 @@ jobs: - name: Fail if the generated client is stale working-directory: agent run: | - if ! git diff --exit-code --stat -- internal/api/client.gen.go; then - echo "::error::internal/api/client.gen.go is out of date with the backend contract." - echo "Run 'go generate ./internal/api' and commit the result." - git diff -- internal/api/client.gen.go + if ! git diff --exit-code --stat -- internal/online/api/client.gen.go; then + echo "::error::internal/online/api/client.gen.go is out of date with the backend contract." + echo "Run 'go generate ./internal/online/api' and commit the result." + git diff -- internal/online/api/client.gen.go exit 1 fi echo "Generated client matches the backend contract." @@ -58,6 +58,6 @@ jobs: - name: Shell syntax working-directory: agent run: | - for f in setup.sh uninstall.sh packaging/*.sh packaging/lib/*.sh; do + for f in setup.sh uninstall.sh packaging/*.sh vm/mbvm; do bash -n "$f" done diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d1c1a93..a72ee2b 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -58,11 +58,6 @@ jobs: - name: Test run: go test ./... - - name: Build release tarballs - run: | - make package - make package-amd64 - - name: Build and sign agent packages run: | make package-mbu @@ -84,8 +79,6 @@ jobs: with: fail_on_unmatched_files: true files: | - build/musallahboard-agent-${{ env.VERSION }}-arm64.tar.gz - build/musallahboard-agent-${{ env.VERSION }}-amd64.tar.gz build/musallahboard-agent-${{ env.VERSION }}-arm64.mbu build/musallahboard-agent-${{ env.VERSION }}-amd64.mbu build/agent-channel-arm64.json diff --git a/Makefile b/Makefile index b5d7c25..0b33a57 100644 --- a/Makefile +++ b/Makefile @@ -12,12 +12,11 @@ RELEASE_KEYS ?= # here ships a binary that reports "dev" forever (or trusts no release key). PKG := github.com/LensBridge/agent LDFLAGS := -s -w -X $(PKG)/internal/version.Version=$(VERSION) \ - -X $(PKG)/internal/trust.BuiltinReleaseKeys=$(RELEASE_KEYS) + -X $(PKG)/internal/core/trust.BuiltinReleaseKeys=$(RELEASE_KEYS) # Where the release channel points boards at (docs/architecture.md 9.4). RELEASE_DOWNLOAD := https://github.com/LensBridge/agent/releases/download/$(RELEASE_TAG) .PHONY: build build-arm64 build-amd64 tidy test clean \ - deploy install-remote install-remote-x86 package package-amd64 \ mbpush mbpush-windows mbpush-macos mbpush-linux \ mbpack package-mbu package-mbu-amd64 @@ -86,77 +85,3 @@ test: clean: rm -rf build/ - -# Replace the binary on a remote host and restart the service (preserves enrollment). -# Usage: make deploy PI=admin@brothers-board.local -deploy: build-arm64 - @if [ -z "$(PI)" ]; then echo "Usage: make deploy PI=user@host"; exit 1; fi - scp build/musallahboard-agent-arm64 packaging/update.sh $(PI):/tmp/ - ssh -t $(PI) 'sudo bash /tmp/update.sh /tmp/musallahboard-agent-arm64' - -# First-time full install on a remote host via the release tarball. -# Usage: make install-remote PI=admin@pi.local TOKEN=xxx BACKEND=https://backend.example.org -# (BACKEND must be https://; for a plain-http dev backend, enroll afterwards on -# the board with `musallahboard-agent enroll ... --insecure-dev`.) -install-remote: package - @if [ -z "$(PI)" ]; then echo "Usage: make install-remote PI=user@host [TOKEN=xxx BACKEND=url]"; exit 1; fi - scp build/musallahboard-agent-$(VERSION)-arm64.tar.gz $(PI):/tmp/ - ssh -t $(PI) 'cd /tmp && tar xzf musallahboard-agent-$(VERSION)-arm64.tar.gz && \ - sudo bash musallahboard-agent-$(VERSION)-arm64/packaging/install.sh \ - $(if $(TOKEN),--token=$(TOKEN)) $(if $(BACKEND),--backend=$(BACKEND))' - -# First-time full install on a remote x86-64 host via the release tarball. -# Usage: make install-remote-x86 HOST=admin@server TOKEN=xxx BACKEND=https://backend.example.org -install-remote-x86: package-amd64 - @if [ -z "$(HOST)" ]; then echo "Usage: make install-remote-x86 HOST=user@host [TOKEN=xxx BACKEND=url]"; exit 1; fi - scp build/musallahboard-agent-$(VERSION)-amd64.tar.gz $(HOST):/tmp/ - ssh -t $(HOST) 'cd /tmp && tar xzf musallahboard-agent-$(VERSION)-amd64.tar.gz && \ - sudo bash musallahboard-agent-$(VERSION)-amd64/packaging/install.sh \ - $(if $(TOKEN),--token=$(TOKEN)) $(if $(BACKEND),--backend=$(BACKEND))' - -# Build a self-contained release tarball ready to ship to a Pi: -# musallahboard-agent-$(VERSION)-arm64.tar.gz -# containing the binary, install/uninstall/update scripts, the systemd units -# (agent, kiosk, self-updater, USB import), the udev rules and the sudoers -# allow-list. On the Pi: -# tar xzf musallahboard-agent-*.tar.gz -# sudo bash musallahboard-agent-*/packaging/install.sh --token=X --backend=Y -package: build-arm64 - @rm -rf build/pkg && mkdir -p build/pkg/musallahboard-agent-$(VERSION)-arm64 - @cp build/musallahboard-agent-arm64 \ - build/pkg/musallahboard-agent-$(VERSION)-arm64/musallahboard-agent - @cp -r packaging build/pkg/musallahboard-agent-$(VERSION)-arm64/ - @sed -i 's/\r//' build/pkg/musallahboard-agent-$(VERSION)-arm64/packaging/*.sh \ - build/pkg/musallahboard-agent-$(VERSION)-arm64/packaging/*.service \ - build/pkg/musallahboard-agent-$(VERSION)-arm64/packaging/*.path \ - build/pkg/musallahboard-agent-$(VERSION)-arm64/packaging/udev/*.rules - @chmod +x build/pkg/musallahboard-agent-$(VERSION)-arm64/packaging/*.sh -# setup.sh is the whole point of the arm64 tarball: the one-line installer -# fetches this archive and runs it. Not shipped in the amd64 one — it is a -# Raspberry Pi wrapper and the x86 host is provisioned by the Packer image. - @cp setup.sh build/pkg/musallahboard-agent-$(VERSION)-arm64/ - @sed -i 's/\r//' build/pkg/musallahboard-agent-$(VERSION)-arm64/setup.sh - @chmod +x build/pkg/musallahboard-agent-$(VERSION)-arm64/setup.sh -# packaging/luks/ holds three extensionless scripts that run inside an -# initramfs, where a stray CR in a shebang produces no diagnosable error at all. - @sed -i 's/\r//' build/pkg/musallahboard-agent-$(VERSION)-arm64/packaging/luks/* - @chmod +x build/pkg/musallahboard-agent-$(VERSION)-arm64/packaging/luks/* - @cp README.md build/pkg/musallahboard-agent-$(VERSION)-arm64/ 2>/dev/null || true - @tar czf build/musallahboard-agent-$(VERSION)-arm64.tar.gz \ - -C build/pkg musallahboard-agent-$(VERSION)-arm64 - @echo "Wrote build/musallahboard-agent-$(VERSION)-arm64.tar.gz" - -package-amd64: build-amd64 - @rm -rf build/pkg && mkdir -p build/pkg/musallahboard-agent-$(VERSION)-amd64 - @cp build/musallahboard-agent-amd64 \ - build/pkg/musallahboard-agent-$(VERSION)-amd64/musallahboard-agent - @cp -r packaging build/pkg/musallahboard-agent-$(VERSION)-amd64/ - @sed -i 's/\r//' build/pkg/musallahboard-agent-$(VERSION)-amd64/packaging/*.sh \ - build/pkg/musallahboard-agent-$(VERSION)-amd64/packaging/*.service \ - build/pkg/musallahboard-agent-$(VERSION)-amd64/packaging/*.path \ - build/pkg/musallahboard-agent-$(VERSION)-amd64/packaging/udev/*.rules - @chmod +x build/pkg/musallahboard-agent-$(VERSION)-amd64/packaging/*.sh - @cp README.md build/pkg/musallahboard-agent-$(VERSION)-amd64/ 2>/dev/null || true - @tar czf build/musallahboard-agent-$(VERSION)-amd64.tar.gz \ - -C build/pkg musallahboard-agent-$(VERSION)-amd64 - @echo "Wrote build/musallahboard-agent-$(VERSION)-amd64.tar.gz" diff --git a/README.md b/README.md index 97bd04a..96a6280 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # MusallahBoard Agent -Go daemon-orchestrator for kiosk devices. Manages Chromium, telemetry, remote commands, and crash recovery. +The device agent for MusallahBoard kiosk Pis. It serves the board from the Pi's own disk, installs signed update packages from USB sticks, laptops and the network, keeps the clock and the kiosk healthy, and, optionally, connects the board to LensBridge for telemetry and remote commands. A board works fully without a network. ## Overview @@ -10,10 +10,10 @@ Go daemon-orchestrator for kiosk devices. Manages Chromium, telemetry, remote co While working on MusallahBoard, it was quickly discovered that a basic websocket to a chromium instance would not suffice for a production kiosk. Thus, this agent was created to manage the kiosk lifecycle, including: -1. Device Enrollment and Identity -2. Deep(er) Chromium and Wayland Control -3. Telemetry and Health Monitoring -4. Remote Command Execution, beyond what the browser can do (reboot, restart kiosk service, tail logs, etc.) +1. The board's identity, from a signed setup file +2. Signed content, board app and agent updates, by USB stick or network +3. Deep(er) Chromium and Wayland control +4. Optionally: telemetry and remote commands (reboot, restart the kiosk, tail logs, etc.) By running a daemon as a systemd service, we offload all complexity from the React frontend and keep the kiosk page as simple as possible. This allows the frontend to be a memory-efficient React SPA rather than a full Electron app (Under 1Gb total memory usage, incl. OS) while the agent handles heavy lifting in the background. @@ -30,38 +30,33 @@ be a memory-efficient React SPA rather than a full Electron app (Under 1Gb total > [!WARNING] > This is your final warning to NOT install the agent on a device that will not act as a 24/7 kiosk! The agent, and related infrastructure, is NOT designed to run on a personal computer! -Installing the agent and setting up related MusallahBoard infrastructure is as simple as +### 1. Install + +On a fresh Raspberry Pi OS Lite (trixie, arm64), as a user with sudo (not as root), while the Pi has internet: ```bash curl -fsSL https://raw.githubusercontent.com/lensbridge/agent/main/setup.sh | bash ``` -Or clone the repo and run the script manually: +It asks for a hostname, an admin username and that admin's SSH public key (the board has no password login; SSH is the maintainer's way in), the time zone, and **LensBridge's content signing public key** (base64, shown in the console; the backend also publishes it at `/api/agent/signing-keys`). The board accepts content and setup files signed by that key only. For an unattended install pass the answers in front of `bash`: `MB_ADMIN_USER=... MB_ADMIN_SSH_KEY="ssh-ed25519 ..." MB_CONTENT_KEY=""`. Re-running it is safe. Then reboot. -```bash -git clone https://github.com/LensBridge/agent.git -cd agent -./setup.sh # as a user with sudo, not as root -``` +The board now shows **"This board is not set up yet. Plug in its setup USB stick."**, with its address for SSH. -Follow the prompts to set the device up (you need an admin username and your SSH public key; the board has no password login), then reboot. For unattended installs, pass them as `MB_ADMIN_USER=... MB_ADMIN_SSH_KEY="ssh-ed25519 ..."` in front of `bash`. Upon reboot, the device will be at a splash screen waiting for enrollment. Once the device has a network connection, that splash also prints its IP address on screen — use it to SSH in without hunting through DHCP leases. +### 2. Plug in the setup stick -To enroll the device, run: +In the LensBridge console, add the board (Devices, Add board), then export its setup file or a USB kit (one stick for several boards: setup files, content, the board app and the agent). Copy the files to a USB stick, at its top level or in a `MusallahBoard/` folder, and plug it in. The board takes its identity from its setup file and then everything else on the stick that is for it, and shows "You can remove the USB stick". It needs no network, now or later. + +If the setup file was exported for an online board, the board also connects to LensBridge whenever it has internet: it binds its own device key to the board in the console (a one-time claim) and from then on syncs content and takes remote commands. A maintainer can instead enroll with a token from the console: ```bash sudo musallahboard-agent enroll --token= --backend= -# Easiest: copy the whole command from the admin portal when you issue the token. ``` -The backend URL must be `https://`, and the WebSocket address the backend hands back must be `wss://` on the same host; the agent refuses anything else, because the enrollment reply pins the keys the board trusts content from. (A development backend on plain http needs `--insecure-dev`; see [Development boards](#development-boards-on-plain-http).) - -The device will then be enrolled and the board will load automatically once its first content and board app packages have synced. The device is now ready to be used as a kiosk! +The backend URL must be `https://`, and the WebSocket address it hands back must be `wss://` on the same host; the agent refuses anything else. ### Development boards on plain http -For a backend running on your own machine without TLS, add `--insecure-dev` to the enroll command. It is saved in `/etc/musallahboard/agent.toml` as `insecure_dev = true`, and the agent logs a warning at every start while it is on: anyone on that board's network can impersonate the backend. Never use it on a deployed board. - -A board enrolled over http before https was required, without `insecure_dev = true`, keeps showing the content it has but no longer talks to the backend (no sync, no update checks, no remote commands). `musallahboard-agent status`, `systemctl status musallahboard-agent` and the journal say why. Re-enroll it over https with `--force`, or, if it is a development board, add `insecure_dev = true` to its `agent.toml` and `sudo systemctl restart musallahboard-agent`. +For a backend running on your own machine without TLS, add `--insecure-dev` to the enroll command. It is saved in `/etc/musallahboard/agent.toml` as `insecure_dev = true`, and the agent logs a warning at every start while it is on: anyone on that board's network can impersonate the backend. Never use it on a deployed board. A board whose config is not safe to use keeps showing the content it has but does not talk to the backend; `musallahboard-agent status` and the journal say why. ## Building @@ -88,49 +83,22 @@ provisioned by `setup.sh`, persists between runs, and can be reset to any agent release (or a build of this checkout): ```bash -vm/mbvm create -vm/mbvm enroll --token= --backend=http://localhost:8080 --insecure-dev +MBVM_CONTENT_KEY= vm/mbvm create +vm/mbvm usb setup-xxxxxxxx.mbu content-xxxxxxxx.mbu vm/mbvm reset --agent=0.2.1 ``` See [vm/README.md](vm/README.md). -## How a board gets updates (v2) - -Every board renders from its own disk: the kiosk always loads the agent's local server at `http://127.0.0.1:8080/`. Content (payloads and posters), the board app and the agent itself all arrive as signed `.mbu` packages, which the board checks against keys it has pinned before installing anything. The network only changes how fresh the board is. [docs/architecture.md](docs/architecture.md) is the full design and the contract with the backend, the frontend and the Android app. - -### Online boards - -Nothing to do. An enrolled board syncs its content from LensBridge every 30 minutes (and straight after an admin changes something), and follows the release channels on GitHub for new board app and agent versions. A new agent is installed by a small root updater that checks it again and rolls it back automatically if it does not start. If the internet drops, the board keeps showing the 7 days of content it already has. - -### Boards without internet - -Set the board up and enroll it online as usual, then turn on the ethernet service port: - -```bash -sudo musallahboard-agent service-port on -``` - -If a DS3231 clock module is fitted, also re-run the setup once with `--rtc`, while the board has internet: - -```bash -curl -fsSL https://raw.githubusercontent.com/lensbridge/agent/main/setup.sh | bash -s -- --service-port --rtc -``` - -The service port turns the ethernet port into a service port: a laptop or phone plugged straight into it gets an address from the board. Turn it off before plugging the board into a real network: `sudo musallahboard-agent service-port off`. - -To update the board, get the packages first, while you have internet: - -- content: LensBridge admin, Devices, the board, Download offline bundle (`musallahboard-content--.mbu`, 14 days) -- board app and agent: `mbpush fetch` (saves the latest `musallahboard-app-*.mbu` and `musallahboard-agent-*-arm64.mbu`) - -Then use any of: +## How a board gets updates -1. **USB stick.** Copy the `.mbu` files to the stick (its root, or a `MusallahBoard/` folder) and plug it into the board. The screen shows progress, and says "You can remove the USB stick" as soon as it has copied what it needs, usually within seconds. One stick can carry content for several boards: each board takes only its own. -2. **Laptop.** Plug into the board's ethernet port and open `http://10.77.0.1/` in a browser, or run `mbpush ...`. `mbpush status` shows what is installed and how far the board's clock is off; an upload also sets the clock from the laptop's. For a board reachable only over SSH: `mbpush --ssh admin@host ...`. -3. **Android app.** Downloads the packages while it has signal, then uploads them over a USB ethernet adapter. +Every board renders from its own disk: the kiosk always loads the agent's local server at `http://127.0.0.1:8080/`. Its identity (setup file), content (payloads and posters), the board app and the agent itself all arrive as signed `.mbu` packages, which the board checks against keys it has pinned before installing anything. The network only changes how fresh the board is. [docs/architecture.md](docs/architecture.md) is the full design and the contract with the backend, the board app and the Android app. -On the board itself: `sudo musallahboard-agent import ...` and `sudo musallahboard-agent status`. +- **USB stick.** Copy `.mbu` files from the console (setup file, content, or a whole USB kit) to a stick and plug it in. One stick can carry packages for many boards: each takes only its own, and only what is newer. Content covers up to 92 days. +- **Release channels.** Any board with internet follows the GitHub release channels for new board app and agent versions (no enrollment needed) and installs them overnight. A new agent is installed by a small root updater that checks it again and rolls it back if it does not stay up. +- **Online boards** (claimed or enrolled) also sync their content from LensBridge every 30 minutes and soon after an admin changes something. +- **Laptop or phone** on the ethernet service port (`sudo musallahboard-agent service-port on`): open `http://10.77.0.1/`, or `mbpush ...`. An upload also sets the board's clock from the laptop's. Turn it off before plugging the board into a real network. A DS3231 clock module: `bash setup.sh --service-port --rtc`. +- **On the board:** `sudo musallahboard-agent import ...` and `musallahboard-agent status`. ### Release signing @@ -143,11 +111,11 @@ make mbpack && build/mbpack keygen # prints a private seed, a public key and - The **private seed** goes in the repository secret `MB_RELEASE_SIGNING_KEY` (and the frontend repo's, for app packages). Keep an offline copy; never commit it. - The **public key** goes in the repository variable `MB_RELEASE_PUBLIC_KEYS` (comma-separated, to allow a second key during a rotation). CI compiles it into the agent (`RELEASE_KEYS`), so every board trusts it without any configuration. -Pushing a tag (`0.3.0`) runs `.github/workflows/release.yml`: tests, builds, signs `musallahboard-agent--.mbu`, and publishes them with `agent-channel-.json`, the release tarballs and the `mbpush` binaries. Locally: `MB_RELEASE_SIGNING_KEY= make package-mbu VERSION=0.3.0 RELEASE_KEYS=`. +Pushing a tag (`0.3.0`) runs `.github/workflows/release.yml`: tests, builds, signs `musallahboard-agent--.mbu`, and publishes them with `agent-channel-.json`, the raw agent binaries setup.sh installs, and the `mbpush` binaries. Locally: `MB_RELEASE_SIGNING_KEY= make package-mbu VERSION=0.3.0 RELEASE_KEYS=`. ### Trust management -Keys live in `/etc/musallahboard/trust.json` (root-owned). Content keys are pinned at enrollment; `sudo musallahboard-agent trust fetch` re-reads them from the backend (for example after a key rotation). Release keys are compiled in and can be extended there. +Keys live in `/etc/musallahboard/trust.json` (root-owned). The content key is pinned by `setup.sh`; `sudo musallahboard-agent trust fetch` re-reads the backend's (for example after a key rotation). Release keys are compiled in and can be extended there. ```bash sudo musallahboard-agent trust show diff --git a/agent b/agent new file mode 100755 index 0000000..a51ac81 Binary files /dev/null and b/agent differ diff --git a/cmd/agent/board.go b/cmd/agent/board.go index f79aad3..c47053a 100644 --- a/cmd/agent/board.go +++ b/cmd/agent/board.go @@ -2,63 +2,52 @@ package main import ( "context" - "encoding/json" - "errors" "log/slog" "net" "os" "runtime" "strings" "sync" - "sync/atomic" "time" "github.com/coreos/go-systemd/v22/daemon" - "github.com/LensBridge/agent/internal/agentupdate" - "github.com/LensBridge/agent/internal/boardsync" - "github.com/LensBridge/agent/internal/cdp" - "github.com/LensBridge/agent/internal/clock" - "github.com/LensBridge/agent/internal/commands" - "github.com/LensBridge/agent/internal/config" - "github.com/LensBridge/agent/internal/events" - "github.com/LensBridge/agent/internal/importer" - "github.com/LensBridge/agent/internal/keystore" - "github.com/LensBridge/agent/internal/kioskurl" - "github.com/LensBridge/agent/internal/localserver" - "github.com/LensBridge/agent/internal/notice" - "github.com/LensBridge/agent/internal/store" - "github.com/LensBridge/agent/internal/trust" - "github.com/LensBridge/agent/internal/updates" - "github.com/LensBridge/agent/internal/updatescreen" - "github.com/LensBridge/agent/internal/uploadserver" + "github.com/LensBridge/agent/internal/core/clock" + "github.com/LensBridge/agent/internal/core/config" + "github.com/LensBridge/agent/internal/core/events" + "github.com/LensBridge/agent/internal/core/importer" + "github.com/LensBridge/agent/internal/core/kiosk" + "github.com/LensBridge/agent/internal/core/localserver" + "github.com/LensBridge/agent/internal/core/notice" + "github.com/LensBridge/agent/internal/core/selfupdate" + "github.com/LensBridge/agent/internal/core/store" + "github.com/LensBridge/agent/internal/core/trust" + "github.com/LensBridge/agent/internal/core/updates" + "github.com/LensBridge/agent/internal/core/uploadserver" + "github.com/LensBridge/agent/internal/online" "github.com/LensBridge/agent/internal/version" - "github.com/LensBridge/agent/internal/wsclient" ) -// kioskWatchInterval is how often the daemon checks that Chromium is not -// sitting on its own error page. The kiosk is ordered after the agent, so -// this is a backstop, not the mechanism. -const kioskWatchInterval = 30 * time.Second - -// startBoard starts everything an enrolled board runs (docs/architecture.md, -// section 3). The local server comes first and is the only part whose failure -// is fatal: without it the board has nothing to show. Everything that needs -// the network or the device key degrades to "not running" instead, because a -// board that cannot reach LensBridge must still show what it has. -func startBoard(ctx context.Context, logger *slog.Logger, cfg *config.Config, safeMode bool, wg *sync.WaitGroup) error { +// startBoard starts everything a board runs (docs/architecture.md, section +// 3), provisioned or not. The local server comes first and is the only part +// whose failure is fatal: without it the board has nothing to show. The +// online layer runs beside the core when agent.toml asks for it, and degrades +// to "not running" on its own, because a board that cannot reach LensBridge +// must still show what it has. +func startBoard(ctx context.Context, logger *slog.Logger, cfg *config.Live, wg *sync.WaitGroup) error { layout := store.Default() if err := os.MkdirAll(layout.Inbox(), 0o770); err != nil { logger.Warn("could not create inbox", "err", err) } + c := cfg.Get() hub := &events.Hub{} - cdpClient := cdp.New("") - screen := updatescreen.New(cdpClient, strings.TrimSuffix(localserver.BaseURL, "/"), logger) - var reporter *agentupdate.Reporter + cdpClient := kiosk.NewClient("") + screen := kiosk.NewScreen(cdpClient, strings.TrimSuffix(localserver.BaseURL, "/"), logger) + var reporter *selfupdate.Reporter imp := importer.New(importer.Deps{ Layout: layout, - DeviceID: cfg.DeviceID, + Config: cfg, AgentVersion: version.Version, Ring: func() (*trust.Ring, error) { return trust.LoadRing(trust.DefaultPath) }, Screen: screen, @@ -66,81 +55,37 @@ func startBoard(ctx context.Context, logger *slog.Logger, cfg *config.Config, sa Events: hub, Logger: logger, }) - reporter = agentupdate.New(agentupdate.Deps{ + reporter = selfupdate.NewReporter(selfupdate.ReporterDeps{ Layout: layout, Version: version.Version, Screen: screen, Banner: hub.Notice, Resume: imp.AgentNotReplaced, Logger: logger, }) keeper := clock.New(layout, logger) - priv, keyErr := keystore.Load(cfg.KeyPath) - if keyErr != nil { - logger.Error("device key unreadable: serving installed content only (no sync, no remote commands)", - "err", keyErr, "keyPath", cfg.KeyPath) - } - // Nothing that talks to the backend is built from an insecure config: - // content sync, its refresh channel and the command WebSocket all take - // their addresses from it (docs/architecture.md, section 11). - transportErr := backendTransport(logger, cfg) - offline := func() string { - if transportErr != nil { - return "not talking to LensBridge: " + transportErr.Error() - } - return "device key unreadable" - } - hour, minute := cfg.UpdateTime() - var syncer *boardsync.Syncer + hour, minute := c.UpdateTime() + // The release channels are public files: any board with a network + // follows them, provisioned and enrolled or not. sched := updates.New(updates.Deps{ - Layout: layout, Importer: imp, Hour: hour, Minute: minute, AutoUpdate: cfg.AutoUpdate(), Logger: logger, - Changed: func(info updates.Info) { hub.UpdatesChanged(info) }, - Check: func(ctx context.Context) error { - if syncer == nil { - return errors.New("this board cannot reach the release channels (" + offline() + ")") - } - return syncer.CheckChannels(ctx) - }, + Layout: layout, Importer: imp, Hour: hour, Minute: minute, AutoUpdate: c.AutoUpdate(), Logger: logger, + AppChannel: c.AppChannelURL(), AgentChannel: c.AgentChannelURL(runtime.GOARCH), + AgentVersion: version.Version, + Changed: func(info updates.Info) { hub.UpdatesChanged(info) }, }) - if keyErr == nil && transportErr == nil { - syncer = boardsync.New(boardsync.Deps{ - Cfg: cfg, Key: priv, Layout: layout, Importer: imp, Updates: sched, - AgentVersion: version.Version, Logger: logger, - }) - } - // The backend connection starts after the local server; its state is - // read through this once it exists. - var backend atomic.Pointer[wsclient.Client] - local := localserver.New(localserver.Deps{ - Layout: layout, DeviceID: cfg.DeviceID, AgentVersion: version.Version, Hub: hub, - Sync: func() any { - if syncer == nil { - // Enabled as configured, so the board app and `status` show - // the reason as a sync error rather than "sync off". - return map[string]any{"enabled": transportErr != nil && cfg.ContentSync(), "lastError": offline()} - } - return syncer.Status() - }, - Weather: func() (json.RawMessage, bool) { - if syncer == nil { - return nil, false - } - return syncer.Weather() - }, + var local *localserver.Server + layer := online.New(online.Deps{ + Config: cfg, Layout: layout, Importer: imp, Updates: sched, Kiosk: cdpClient, + BoardReport: func() any { return local.Status().Board() }, + AgentVersion: version.Version, Logger: logger, + }) + local = localserver.New(localserver.Deps{ + Layout: layout, Config: cfg, AgentVersion: version.Version, Hub: hub, + Sync: layer.Sync, + Weather: layer.Weather, + Backend: layer.Backend, UpdateActive: screen.Active, Updates: sched.Info, Clock: keeper.Info, - Backend: func() any { - if ws := backend.Load(); ws != nil { - s := ws.State() - return &s - } - if transportErr != nil { - return map[string]any{"connected": false, "lastError": offline()} - } - return nil - }, - ServicePort: cfg.ServicePort(), - USBImport: cfg.USBImport(), - Logger: logger, + Logger: logger, }) ln, err := net.Listen("tcp", localserver.ListenAddr) if err != nil { @@ -155,19 +100,11 @@ func startBoard(ctx context.Context, logger *slog.Logger, cfg *config.Config, sa } }) - // Only now can the kiosk find something at the URL it is given. - if err := kioskurl.WriteLocal(kioskurl.DefaultOutPath); err != nil { - logger.Warn("could not write kiosk url", "err", err) - } _, _ = daemon.SdNotify(false, daemon.SdNotifyReady) - if transportErr != nil { - _, _ = daemon.SdNotify(false, "STATUS=serving installed content only; refusing the backend: "+transportErr.Error()) - } else { - _, _ = daemon.SdNotify(false, "STATUS=serving the board on "+localserver.ListenAddr) - } + _, _ = daemon.SdNotify(false, "STATUS=serving the board on "+localserver.ListenAddr) - logInstalled(logger, layout, cfg) - goRun(wg, func() { watchKiosk(ctx, logger, cdpClient, screen.Active) }) + logInstalled(logger, layout, c) + goRun(wg, func() { kiosk.Watch(ctx, logger, cdpClient, localserver.BaseURL, screen.Active) }) goRun(wg, func() { // First say how an agent update that restarted us went: the rest of // its batch may be waiting in the inbox, and belongs on the same @@ -177,53 +114,25 @@ func startBoard(ctx context.Context, logger *slog.Logger, cfg *config.Config, sa }) goRun(wg, func() { keeper.Run(ctx) }) goRun(wg, func() { sched.Run(ctx) }) + goRun(wg, func() { layer.Run(ctx) }) - if cfg.ServicePort() { + if c.ServicePort() { startUploadServer(ctx, logger, cfg, layout, imp, keeper, screen, wg) } - - if syncer != nil { - goRun(wg, func() { syncer.Run(ctx) }) - ws := startCommandChannel(ctx, logger, cfg, priv, safeMode, cdpClient, syncer, sched, - func() any { return local.Status().Board() }, wg) - backend.Store(ws) - } return nil } -// backendTransport checks that the config may be used to talk to the -// backend (config.CheckTransport) and says so loudly at every start when it -// may not, or when it may only because of the insecure_dev opt-in. A board -// enrolled over plain http before https was required lands here: it keeps -// showing what it has, and the log, `systemctl status`, `musallahboard-agent -// status` and the board app's sync error all carry the reason and the fix. -func backendTransport(logger *slog.Logger, cfg *config.Config) error { - if err := cfg.CheckTransport(); err != nil { - logger.Error("REFUSING TO TALK TO THE BACKEND: this board's config is not safe to use. "+ - "Serving installed content only: no content sync, no release channel checks, no remote commands. "+ - "Re-enroll it over https (sudo musallahboard-agent enroll --force --token=... --backend=https://...), "+ - "or, for a development board only, add insecure_dev = true to "+defaultConfigPath+" and restart the agent.", - "err", err, "backendUrl", cfg.BackendURL, "websocketUrl", cfg.WebSocketURL) - return err - } - if cfg.InsecureDev() { - logger.Warn("INSECURE DEVELOPMENT BOARD: insecure_dev = true, so this board accepts a plaintext backend. "+ - "Anyone on its network can impersonate the backend: send it content, reboot it, read its screen and logs. "+ - "Never deploy a board like this.", - "backendUrl", cfg.BackendURL, "websocketUrl", cfg.WebSocketURL) - } - return nil -} - -func startUploadServer(ctx context.Context, logger *slog.Logger, cfg *config.Config, layout store.Layout, - imp *importer.Importer, keeper *clock.Keeper, screen *updatescreen.Screen, wg *sync.WaitGroup) { +func startUploadServer(ctx context.Context, logger *slog.Logger, cfg *config.Live, layout store.Layout, + imp *importer.Importer, keeper *clock.Keeper, screen *kiosk.Screen, wg *sync.WaitGroup) { ln, err := uploadserver.Listen() if err != nil { logger.Error("could not start the upload server; USB sticks still work", "addr", uploadserver.ListenAddr, "err", err) return } srv := uploadserver.New(uploadserver.Deps{ - Layout: layout, DeviceID: cfg.DeviceID, AgentVersion: version.Version, Importer: imp, + Layout: layout, + DeviceID: func() string { return cfg.Get().DeviceID }, + AgentVersion: version.Version, Importer: imp, ApplyClientTime: func(unix int64, b importer.Batch) uploadserver.ClockReport { r := keeper.ApplyClientTime(unix, b) return uploadserver.ClockReport{DriftSeconds: r.DriftSeconds, Adjusted: r.Adjusted, Note: r.Note} @@ -241,217 +150,6 @@ func startUploadServer(ctx context.Context, logger *slog.Logger, cfg *config.Con }) } -// startCommandChannel holds the backend WebSocket (telemetry and remote -// commands) open. config.refresh also asks the content syncer for a sync now; -// update.install_now checks the release channels and installs at once. -func startCommandChannel(ctx context.Context, logger *slog.Logger, cfg *config.Config, priv []byte, - safeMode bool, cdpClient *cdp.Client, syncer *boardsync.Syncer, sched *updates.Scheduler, - boardReport func() any, wg *sync.WaitGroup) *wsclient.Client { - wsClient := wsclient.New(cfg, priv, logger, version.Version, safeMode) - wsClient.SetPageProber(cdpClient) - wsClient.SetBoardReport(boardReport) - registry := commands.NewRegistry() - registry.Register(&commands.ChromeReload{CDP: cdpClient}) - registry.Register(&commands.ChromeScreenshot{CDP: cdpClient}) - registry.Register(&commands.ConfigRefresh{CDP: cdpClient, Before: syncer.Trigger}) - registry.Register(&commands.KioskRestart{}) - registry.Register(&commands.SystemReboot{}) - registry.Register(&commands.LogsTail{}) - registry.Register(&commands.UpdateInstallNow{Run: sched.CheckAndInstall}) - logger.Info("command handlers registered", "kinds", registry.Kinds()) - wsClient.SetCommandHandler(commands.NewDispatcher(registry, logger).Handle) - goRun(wg, func() { wsClient.Run(ctx) }) - return wsClient -} - -// Kiosk self-healing (watchKiosk). The page is probed every -// kioskWatchInterval. A crashed renderer is certain after one probe; a page -// that does not answer may be busy (a large poster decoding on a Pi), so it -// gets kioskHungThreshold probes. Then the watcher reloads the page; if the -// page is still dead after that, it restarts the kiosk unit. Restarts back off -// from kioskRestartMinGap to kioskRestartMaxGap, and the backoff only starts -// over after the page has been healthy for kioskRestartResetAfter, so a page -// that never comes back costs at most one reload and one restart an hour. -const ( - kioskProbeTimeout = 5 * time.Second - kioskCrashThreshold = 1 - kioskHungThreshold = 3 - kioskRestartMinGap = 5 * time.Minute - kioskRestartMaxGap = time.Hour - kioskRestartResetAfter = time.Hour -) - -// watchKiosk keeps the kiosk on the board: it navigates Chromium back if it -// lands on its own error page (the server restarting under it, for instance) -// and heals a crashed or hung page (kioskHealer). -func watchKiosk(ctx context.Context, logger *slog.Logger, c *cdp.Client, updateActive func() bool) { - h := newKioskHealer(logger, c, updateActive) - t := time.NewTicker(kioskWatchInterval) - defer t.Stop() - for { - select { - case <-ctx.Done(): - return - case <-t.C: - } - h.tick(ctx) - } -} - -// kioskHealer is the watcher's state between ticks. Its browser and systemd -// operations are fields so the escalation can be tested without either. -type kioskHealer struct { - log *slog.Logger - now func() time.Time - updateActive func() bool - target func(context.Context) (cdp.Target, error) - navigate func(context.Context, cdp.Target, string) error - health func(context.Context) error - reload func(context.Context) error - restart func(context.Context) error - - fails int // consecutive dead-page probes - reloaded bool // reloaded since the last restart (or since healthy) - restarts int // restarts since the backoff last started over - nextRestart time.Time // no restart before this - healthySince time.Time // zero while the page is dead - waitLogged bool -} - -func newKioskHealer(logger *slog.Logger, c *cdp.Client, updateActive func() bool) *kioskHealer { - if updateActive == nil { - updateActive = func() bool { return false } - } - return &kioskHealer{ - log: logger, - now: time.Now, - updateActive: updateActive, - target: c.FirstPageTarget, - navigate: func(ctx context.Context, t cdp.Target, url string) error { - return c.Call(ctx, t, "Page.navigate", map[string]any{"url": url}, nil) - }, - health: c.PageHealth, - reload: c.PageReload, - restart: func(ctx context.Context) error { - // The same privileged path as the kiosk.restart remote command - // (sudo -n systemctl restart, allowed by the sudoers drop-in). - _, err := (&commands.KioskRestart{}).Execute(ctx, nil, func(string, string, *int) {}) - return err - }, - } -} - -func (h *kioskHealer) tick(ctx context.Context) { - // The update screen is driven over CDP by the importer and may be - // waiting on an agent restart; nothing here may navigate under it. - if h.updateActive() { - h.fails = 0 - return - } - - cctx, cancel := context.WithTimeout(ctx, kioskProbeTimeout) - target, err := h.target(cctx) - cancel() - if err == nil && strings.HasPrefix(target.URL, "chrome-error:") { - h.log.Info("kiosk is on an error page; returning it to the board") - cctx, cancel := context.WithTimeout(ctx, kioskProbeTimeout) - _ = h.navigate(cctx, target, localserver.BaseURL) - cancel() - return - } - if err != nil { - // No browser, or no page yet: starting, or restarting (perhaps - // because we asked). systemd's Restart=always owns that case. - return - } - - cctx, cancel = context.WithTimeout(ctx, kioskProbeTimeout) - err = h.health(cctx) - cancel() - if ctx.Err() != nil { - return - } - - threshold := 0 - switch { - case errors.Is(err, cdp.ErrPageCrashed): - threshold = kioskCrashThreshold - case errors.Is(err, cdp.ErrPageUnresponsive): - threshold = kioskHungThreshold - case errors.Is(err, cdp.ErrDebuggerUnreachable), errors.Is(err, cdp.ErrNoPageTarget): - // The browser went away between the two calls: not the page's fault, - // and not proof it recovered either. - return - default: - // Answered, or between documents, or the hook threw: the page is - // alive. A navigation in flight is not a failure. - h.healthy() - return - } - - h.healthySince = time.Time{} - h.fails++ - if h.fails < threshold { - h.log.Warn("kiosk page is not answering", "err", err, "failures", h.fails, "url", target.URL) - return - } - h.heal(ctx, err, target.URL) -} - -func (h *kioskHealer) healthy() { - now := h.now() - if h.fails > 0 || h.reloaded { - h.log.Info("kiosk page is answering again") - } - h.fails, h.reloaded, h.waitLogged = 0, false, false - if h.healthySince.IsZero() { - h.healthySince = now - } - if h.restarts > 0 && now.Sub(h.healthySince) >= kioskRestartResetAfter { - h.restarts, h.nextRestart = 0, time.Time{} - } -} - -// heal takes the next step for a dead page: a reload, at most once until the -// page answers again or the kiosk restarts; then a restart, at most once per -// backoff gap. A page that recovers each time it is reloaded is reloaded each -// time it dies, which is what it needs; a page that never recovers gets one -// reload and one restart per gap. -func (h *kioskHealer) heal(ctx context.Context, cause error, url string) { - if !h.reloaded { - h.fails, h.reloaded = 0, true - h.log.Warn("kiosk page is dead; reloading it", "err", cause, "url", url) - cctx, cancel := context.WithTimeout(ctx, kioskProbeTimeout) - if err := h.reload(cctx); err != nil { - h.log.Warn("could not reload the kiosk page", "err", err) - } - cancel() - return - } - - now := h.now() - if now.Before(h.nextRestart) { - if !h.waitLogged { - h.log.Error("kiosk page is still dead; waiting before restarting the kiosk again so a broken page cannot restart it in a loop", - "err", cause, "url", url, "nextAttempt", h.nextRestart.Format(time.RFC3339)) - h.waitLogged = true - } - return - } - - h.fails, h.reloaded, h.waitLogged = 0, false, false - gap := min(kioskRestartMinGap< Copy update packages from a USB stick - musallahboard-agent splash install [path] Install the enrollment splash page Enroll flags: --token One-time enrollment token from the admin portal @@ -135,7 +118,7 @@ func runEnroll(args []string) { // Enrolling again gives the board a new identity; the old device stays // in the portal, orphaned, until someone revokes it. Only on purpose. - if old, err := config.Load(*configPath); err == nil && !*force { + if old, err := config.Load(*configPath); err == nil && old.WebSocketURL != "" && !*force { fmt.Fprintf(os.Stderr, "This board is already enrolled (device %s).\n", old.DeviceID) fmt.Fprintln(os.Stderr, "Enrolling again gives it a new identity; revoke the old device in the portal afterwards.") fmt.Fprintln(os.Stderr, "To go ahead, run the same command with --force.") @@ -159,8 +142,9 @@ func runEnroll(args []string) { fail("enrolled, but the config it wrote cannot be read: %v", err) } fmt.Printf("Enrolled as device %s.\n", cfg.DeviceID) - fmt.Println("The board switches from the enrollment screen to MusallahBoard within a few seconds, then") - fmt.Println("downloads its board app and content. Check on it with: musallahboard-agent status") + restartAgent() + fmt.Println("The board connects to LensBridge within a few seconds, then syncs its content.") + fmt.Println("Check on it with: musallahboard-agent status") } func runDaemon() { @@ -171,10 +155,6 @@ func runDaemon() { defer cancel() var wg sync.WaitGroup - - // Started before the config gate: awaitEnrollment below can hold the - // process for days, and systemd's WatchdogSec does not pause for it. - // It pings only while hb is fresh (watchdogLoop). hb := newHeartbeat() wg.Add(1) go func() { @@ -182,47 +162,30 @@ func runDaemon() { watchdogLoop(ctx, logger, hb) }() - cfg, err := config.Load(defaultConfigPath) + // No agent.toml is an unprovisioned board: it runs all the same, shows + // its "not set up yet" screen and takes USB sticks. An unreadable one is + // reported and treated the same, so the screen still says something. + cfg, err := config.Open(defaultConfigPath) if err != nil { - logger.Info("not enrolled yet — entering pre-enrollment mode", "reason", err) - cfg = awaitEnrollment(ctx, logger, hb) - if cfg == nil { // context cancelled while waiting - wg.Wait() - logger.Info("shutdown complete") - return - } - logger.Info("enrollment detected", "deviceId", cfg.DeviceID) + logger.Error("cannot read the agent config; running as an unprovisioned board", "err", err, "path", defaultConfigPath) } - - sm := safemode.New(defaultStateDir) - safeMode := sm.OnStartup() - if safeMode { - logger.Warn("agent starting in safe mode (repeated crashes detected)") + if c := cfg.Get(); c.Provisioned() { + logger.Info("board identity", "deviceId", c.DeviceID, "displayName", c.DisplayName, "online", c.Online()) + } else { + logger.Info("this board is not set up yet: waiting for its setup USB stick") } - hb.beat() - if err := startBoard(ctx, logger, cfg, safeMode, &wg); err != nil { + if err := startBoard(ctx, logger, cfg, &wg); err != nil { logger.Error("could not start", "err", err) os.Exit(1) } - // From now on the heartbeat is the local server answering. + // The heartbeat is the local server answering. wg.Add(1) go func() { defer wg.Done() probeLoop(ctx, hb, "http://"+localserver.ListenAddr+"/api/local/status", livenessProbeInterval) }() - wg.Add(1) - go func() { - defer wg.Done() - select { - case <-time.After(stableRunDuration): - sm.OnSuccessfulRun() - logger.Info("crash counter reset (agent stable)") - case <-ctx.Done(): - } - }() - <-ctx.Done() logger.Info("shutdown signal received") _, _ = daemon.SdNotify(false, daemon.SdNotifyStopping) @@ -230,74 +193,12 @@ func runDaemon() { logger.Info("shutdown complete") } -// awaitEnrollment blocks until a usable config appears at defaultConfigPath, -// painting this device's IP address onto the kiosk splash while it waits. -// Returns nil if ctx is cancelled first. -// -// Before this existed the daemon exited(1) on a missing config, so a freshly -// imaged board burned through systemd's StartLimitBurst within a minute and -// then sat dead behind a static "waiting for enrollment" card. Finding the box -// to SSH into meant plugging in a keyboard or trawling the router's DHCP -// leases. The screen is the one output an appliance always has, so an -// unenrolled agent now stays up and uses it: no network client, no command -// dispatcher, no key — just a poll loop and a CDP push. -// -// Waiting is a legitimate running state rather than a slow start, so we report -// READY to systemd up front; otherwise Type=notify would hold the unit in -// "activating" and kill it at TimeoutStartSec. -func awaitEnrollment(ctx context.Context, logger *slog.Logger, hb *heartbeat) *config.Config { - _, _ = daemon.SdNotify(false, daemon.SdNotifyReady) - _, _ = daemon.SdNotify(false, "STATUS=waiting for enrollment") - - cdpClient := cdp.New("") - - var last netinfo.Info - var reported bool - - t := time.NewTicker(enrollPollInterval) - defer t.Stop() - for { - // Every step below is bounded, so a loop that stops coming round - // is stuck, and the watchdog should restart us. - hb.beat() - info := netinfo.Collect(ctx) - if !reported || !info.Equal(last) { - logger.Info("device network address", - "ipv4", info.IPv4, - "ssid", info.SSID, - "hostname", info.Hostname, - ) - last, reported = info, true - } - - // Chromium may not be up yet, or may be mid-restart, and once enrolled - // the board replaces the splash entirely — a push that finds no hook is - // the normal case, not an error worth a log line every tick. - switch err := splash.PushNetInfo(ctx, cdpClient, info, version.Version); { - case err == nil, errors.Is(err, splash.ErrNoSplash): - default: - logger.Debug("could not update enrollment splash", "err", err) - } - - if cfg, err := config.Load(defaultConfigPath); err == nil { - return cfg - } - - select { - case <-t.C: - case <-ctx.Done(): - return nil - } - } -} - // The systemd watchdog (WatchdogSec= in musallahboard-agent.service). // // A ping on a timer of its own would only prove that the Go runtime still // schedules goroutines. So the agent pings only while a heartbeat is fresh, -// and the heartbeat is bumped by real work: before enrollment by the poll -// loop in awaitEnrollment (every 5 s), and once enrolled by probeLoop, which -// asks the agent's own local server for /api/local/status. Answering that +// and the heartbeat is bumped by real work: probeLoop, which asks the +// agent's own local server for /api/local/status. Answering that // takes the HTTP server and the locks of the sync, backend, update and clock // state, i.e. what the board and the admin portal depend on. None of it // waits on the network or on the disk beyond a few small files, so an idle or diff --git a/cmd/agent/selfupdate.go b/cmd/agent/selfupdate.go index 4970cac..4639827 100644 --- a/cmd/agent/selfupdate.go +++ b/cmd/agent/selfupdate.go @@ -8,7 +8,7 @@ import ( "os/signal" "syscall" - "github.com/LensBridge/agent/internal/selfupdate" + "github.com/LensBridge/agent/internal/core/selfupdate" "github.com/LensBridge/agent/internal/version" ) diff --git a/cmd/agent/serviceport_cli.go b/cmd/agent/serviceport_cli.go index ea877f5..dae589b 100644 --- a/cmd/agent/serviceport_cli.go +++ b/cmd/agent/serviceport_cli.go @@ -12,7 +12,7 @@ import ( "syscall" "time" - "github.com/LensBridge/agent/internal/config" + "github.com/LensBridge/agent/internal/core/config" ) // Names shared with setup.sh --service-port. Change them together. @@ -44,7 +44,8 @@ func requireRoot(cmd string) { } } -// loadConfigCLI loads the enrolled config, explaining the usual failures. +// loadConfigCLI loads agent.toml (empty on an unprovisioned board), +// explaining the usual failures. func loadConfigCLI() *config.Config { cfg, err := config.Load(defaultConfigPath) switch { @@ -52,8 +53,6 @@ func loadConfigCLI() *config.Config { return cfg case errors.Is(err, fs.ErrPermission): fail("cannot read %s (permission denied). Run this with sudo.", defaultConfigPath) - case errors.Is(err, fs.ErrNotExist): - fail("this board is not enrolled yet (%s does not exist). Enroll it online first:\n sudo musallahboard-agent enroll --token= --backend=", defaultConfigPath) default: fail("%v", err) } @@ -80,7 +79,7 @@ func runServicePort(args []string) { os.Exit(2) } requireRoot("service-port " + rest[0]) - loadConfigCLI() // must be enrolled; SetServicePort rewrites this file + loadConfigCLI() // must be readable; SetServicePort rewrites this file // Turning it off over the service port kills this SSH session part way // through. Keep going when the terminal hangs up; every step left is one @@ -200,7 +199,7 @@ func servicePortOff() { fmt.Println("Content keeps syncing from LensBridge whenever the board can reach it.") } -// restartAgent restarts the daemon so it starts or stops the upload server. +// restartAgent restarts the daemon, so it reads the config a command changed. func restartAgent() { if out, err := runCmd("systemctl", "restart", agentUnit); err != nil { fail("could not restart %s: %v\n%s", agentUnit, err, out) diff --git a/cmd/agent/splash_cli.go b/cmd/agent/splash_cli.go deleted file mode 100644 index 307c60a..0000000 --- a/cmd/agent/splash_cli.go +++ /dev/null @@ -1,41 +0,0 @@ -package main - -import ( - "fmt" - "os" - "path/filepath" - - "github.com/LensBridge/agent/internal/fsutil" - "github.com/LensBridge/agent/packaging" -) - -// defaultSplashPath is where the kiosk loads the enrollment splash from -// (packaging/start-kiosk.sh). -const defaultSplashPath = "/usr/share/musallahboard/waiting.html" - -// runSplash is `splash install [dir-or-waiting.html path]`: write the kiosk's -// local pages embedded in this binary: the enrollment splash (waiting.html) -// and the page it waits on while the agent starts (starting.html). setup.sh -// runs it once the binary is in place, and the self-updater after each -// update, so the pages always match the agent. -func runSplash(args []string) { - if len(args) < 1 || args[0] != "install" || len(args) > 2 { - fmt.Fprintln(os.Stderr, "usage: musallahboard-agent splash install [path]") - os.Exit(2) - } - path := defaultSplashPath - if len(args) == 2 { - path = args[1] - } - requireRoot("splash install") - if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { - fail("%v", err) - } - if err := fsutil.WriteAtomic(path, packaging.WaitingHTML, 0o644); err != nil { - fail("could not write %s: %v", path, err) - } - starting := filepath.Join(filepath.Dir(path), "starting.html") - if err := fsutil.WriteAtomic(starting, packaging.StartingHTML, 0o644); err != nil { - fail("could not write %s: %v", starting, err) - } -} diff --git a/cmd/agent/status_cli.go b/cmd/agent/status_cli.go index c945f07..1c0af00 100644 --- a/cmd/agent/status_cli.go +++ b/cmd/agent/status_cli.go @@ -11,11 +11,11 @@ import ( "strings" "time" - "github.com/LensBridge/agent/internal/cdp" - "github.com/LensBridge/agent/internal/clock" - "github.com/LensBridge/agent/internal/localserver" - "github.com/LensBridge/agent/internal/store" - "github.com/LensBridge/agent/internal/trust" + "github.com/LensBridge/agent/internal/core/clock" + "github.com/LensBridge/agent/internal/core/kiosk" + "github.com/LensBridge/agent/internal/core/localserver" + "github.com/LensBridge/agent/internal/core/store" + "github.com/LensBridge/agent/internal/core/trust" "github.com/LensBridge/agent/internal/version" ) @@ -137,7 +137,7 @@ func localTime(v any) string { func kioskShowing() string { ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second) defer cancel() - t, err := cdp.New("").FirstPageTarget(ctx) + t, err := kiosk.NewClient("").FirstPageTarget(ctx) if err != nil { return "NOTHING: the kiosk browser is not running (systemctl status musallahboard-kiosk)" } @@ -148,8 +148,6 @@ func kioskShowing() string { return "MusallahBoard" case strings.Contains(u, "starting.html"): return "the starting page, waiting for the agent" - case strings.Contains(u, "waiting.html"): - return "the enrollment screen" case strings.HasPrefix(u, "chrome-error:"): return "A BROWSER ERROR PAGE (the agent recovers it within a minute)" default: @@ -161,7 +159,14 @@ func printStatus(st cliStatus) { row := func(k, format string, args ...any) { fmt.Printf(" %-18s %s\n", k+":", fmt.Sprintf(format, args...)) } - row("Device", "%s", st.DeviceID) + switch { + case st.DeviceID == "": + row("Device", "NOT SET UP YET: plug in its setup USB stick (from LensBridge, Devices, Setup file)") + case st.DisplayName != "": + row("Device", "%s (%s)", st.DisplayName, st.DeviceID) + default: + row("Device", "%s", st.DeviceID) + } if st.Daemon { row("Agent", "%s (running)", st.AgentVersion) } else { @@ -171,7 +176,7 @@ func printStatus(st cliStatus) { row("Screen", "%s", kioskShowing()) switch b, _ := st.Backend.(map[string]any); { case b == nil: - row("LensBridge", "not connected: no device key") + row("LensBridge", "offline board (no backend in its setup file)") case b["connected"] == true: row("LensBridge", "connected since %s", localTime(b["since"])) case b["lastError"] != nil && b["lastError"] != "": diff --git a/cmd/agent/trust_cli.go b/cmd/agent/trust_cli.go index 12e6d8c..8dcff5b 100644 --- a/cmd/agent/trust_cli.go +++ b/cmd/agent/trust_cli.go @@ -9,9 +9,9 @@ import ( "strings" "time" - "github.com/LensBridge/agent/internal/config" - "github.com/LensBridge/agent/internal/enroll" - "github.com/LensBridge/agent/internal/trust" + "github.com/LensBridge/agent/internal/core/config" + "github.com/LensBridge/agent/internal/core/trust" + "github.com/LensBridge/agent/internal/online/enroll" ) // runTrust is `trust show|add|remove|fetch` (docs/architecture.md, section diff --git a/cmd/agent/update_cli.go b/cmd/agent/update_cli.go index 2af8417..1d9ed1a 100644 --- a/cmd/agent/update_cli.go +++ b/cmd/agent/update_cli.go @@ -8,10 +8,10 @@ import ( "os" "time" - "github.com/LensBridge/agent/internal/fsutil" - "github.com/LensBridge/agent/internal/importer" - "github.com/LensBridge/agent/internal/store" - "github.com/LensBridge/agent/internal/updates" + "github.com/LensBridge/agent/internal/core/fsutil" + "github.com/LensBridge/agent/internal/core/importer" + "github.com/LensBridge/agent/internal/core/store" + "github.com/LensBridge/agent/internal/core/updates" ) // updateWait is how long `update now` waits: a download on a slow link, then diff --git a/cmd/agent/usbimport.go b/cmd/agent/usbimport.go index f14be7a..ae31eb0 100644 --- a/cmd/agent/usbimport.go +++ b/cmd/agent/usbimport.go @@ -8,9 +8,9 @@ import ( "os/signal" "syscall" - "github.com/LensBridge/agent/internal/config" - "github.com/LensBridge/agent/internal/notice" - "github.com/LensBridge/agent/internal/usbimport" + "github.com/LensBridge/agent/internal/core/config" + "github.com/LensBridge/agent/internal/core/notice" + "github.com/LensBridge/agent/internal/core/usbimport" ) // runUSBImport is `usb-import ` (docs/architecture.md, section @@ -23,13 +23,13 @@ func runUSBImport(args []string) { } requireRoot("usb-import") + // An unprovisioned board (no agent.toml) takes sticks too: its setup + // file comes on one. An unreadable config does not stop a stick either; + // the daemon decides what to install. cfg, err := config.Load(defaultConfigPath) if err != nil { - // Not enrolled (or config unreadable): there is no daemon importing - // yet, so there is nothing to hand the stick to. Not an error for - // the unit; the stick is simply ignored. - fmt.Printf("USB import: ignoring %s: this board is not set up yet (%v)\n", args[0], err) - return + fmt.Printf("USB import: the agent config is unreadable (%v); reading %s anyway\n", err, args[0]) + cfg = &config.Config{} } if !cfg.USBImport() { fmt.Printf("USB import: ignoring %s: usb_import is off in the agent config\n", args[0]) diff --git a/cmd/mbpack/main.go b/cmd/mbpack/main.go index feaa88f..f0ed9bc 100644 --- a/cmd/mbpack/main.go +++ b/cmd/mbpack/main.go @@ -24,8 +24,8 @@ import ( "strings" _ "time/tzdata" // content timezones must resolve on any OS - "github.com/LensBridge/agent/internal/mbu" - "github.com/LensBridge/agent/internal/trust" + "github.com/LensBridge/agent/internal/core/mbu" + "github.com/LensBridge/agent/internal/core/trust" ) func main() { diff --git a/docs/architecture.md b/docs/architecture.md index e3e1a63..b09d078 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,72 +1,87 @@ -# MusallahBoard on-device architecture (v2, local-first) +# MusallahBoard on-device architecture (v3, offline-first) This document is the contract for everything that runs on a board, and for the -pieces that feed it: the LensBridge backend, the frontend build, `mbpush` on a -laptop and the Android app. If code and this file disagree, fix one of them -deliberately. It replaces the v1 `docs/offline.md`. - -## 1. Why v1 was replaced - -The v1 offline design was bolted onto an online-only board. The audit found: - -| # | v1 problem | Consequence | -|---|---|---| -| A1 | Two runtime paths. Online boards loaded the hosted site and the live API; offline boards were served by the agent. A manual `mode` switch picked one. | An online board that lost internet mid-day, or rebooted during an outage, had nothing to show. Offline behaviour was only ever exercised on offline boards. | -| A2 | Bundles were unsigned. Trust lived entirely in the transport (an SSH push account). | Anyone holding any push key, or any compromised laptop, could put arbitrary content on a board. The device id is not a secret (it was in the kiosk URL). | -| A3 | No anti-rollback. | An old bundle could be replayed over a new one. | -| A4 | The SPA update path (`app install`) accepted any tarball, and the agent itself could only be updated over SSH by an admin. | Offline boards were stuck on whatever software they left the building with. | -| A5 | The push path needed an extra Unix account, per-board key provisioning, sshd surgery, a sudo rule and a root gate parsing `SSH_ORIGINAL_COMMAND`. Host keys were not checked. | Large attack surface and a lot of operational steps for "copy a file to a board". | -| A6 | The clock could be set to anything in 2026-2100 by whoever held a push key. | Wrong prayer times, wrong day's content. | -| A7 | The kiosk and the local server raced at boot; a timer navigated away from Chromium's error page. | Occasional blank board after boot. | - -## 2. Principles - -1. **Local-first, always.** Every board, online or not, renders from state on - its own disk: the kiosk always loads `http://127.0.0.1:8080/`, served by the - agent. The network only changes how fresh that state is. There is no - online/offline mode. -2. **Everything that changes the board is a signed package.** Content, the - board app (SPA) and the agent binary all arrive as `.mbu` files, verified - against keys pinned on the device. Transports (backend sync, USB stick, - laptop, phone) are untrusted pipes that all feed one importer. +pieces that feed it: the LensBridge backend and console, the board app, `mbpush` +on a laptop and the Android app. If code and this file disagree, fix one of +them deliberately. + +## 1. Principles + +1. **Offline-first.** A board is fully functional with no network, ever. It + renders from state on its own disk: the kiosk always loads + `http://127.0.0.1:8080/`, served by the agent. It is set up, and updated, + by USB stick. A network only makes it fresher. +2. **Everything that changes the board is a signed package.** Its identity + (a setup file), content, the board app and the agent binary all arrive as + `.mbu` files, verified against keys pinned on the board. Transports + (USB stick, laptop, phone, backend sync, release channels) are untrusted + pipes into one importer. 3. **Two trust roots.** The backend holds a *content* key and can only sign - content. Software (app and agent) is signed by a separate *release* key held - offline or in CI. A compromised backend can put the wrong posters on a - screen; it cannot run code on a board. -4. **Monotonic.** Packages never go backwards (content by sequence, software by - version). Re-sending what is installed is a harmless no-op. + content and setup files. Software (app and agent) is signed by a separate + *release* key held offline or in CI and compiled into the agent. A + compromised backend can put the wrong posters on a screen; it cannot run + code on a board. +4. **Monotonic.** Packages never go backwards (content and setup files by + sequence, software by version). Re-sending what is installed is a no-op. 5. **Least privilege.** The daemon runs unprivileged. Two small root entry - points exist, each of which re-verifies what it is handed: the agent - self-updater and the USB import helper. + points exist, each of which re-verifies what it is handed or verifies + nothing at all: the agent self-updater and the USB copy helper. 6. **Atomic and recoverable.** Every install is stage, fsync, rename, symlink swap. A power cut at any point leaves the previous state serving. A new - agent is on probation for its first minutes and is rolled back - automatically if it fails it; an interrupted agent update is finished - from its journal at the next boot. + agent is on probation and is rolled back if it fails it. +7. **The fleet layer is optional.** Enrollment or claim, the agent WebSocket, + telemetry, remote commands and backend content sync run beside the board, + never under it. -## 3. Components +## 2. Board states + +What a board is, is what its `agent.toml` says (section 11): + +| State | agent.toml | What runs | +|---|---|---| +| unprovisioned | absent (or no `device_id`) | the whole core; the screen is the setup screen; USB sticks, uploads and imports are taken | +| provisioned, offline | `device_id`, `display_name` | the whole core, the board app | +| provisioned, online, not yet claimed | plus `backend_url`, `claim_secret` | the core; the online layer claims, retrying while offline | +| online | plus `websocket_url`, and `agent.key` | the core and the whole online layer | + +## 3. Components and code layout ``` - LensBridge backend (content key) GitHub releases (release key, CI) - | signed content .mbu | signed app/agent .mbu + channel json - online: device-signed HTTPS online: HTTPS (channel) - | | - laptop (mbpush / browser) --HTTP upload--+ | - Android app ----------------HTTP upload--+ | - USB stick --> usb-import helper (root) --+--> inbox | - sudo musallahboard-agent import ---------+ | | - v v - +--------------------------- musallahboard-agent (daemon, unprivileged) ---------------------------+ - | importer: verify signature, type, device, monotonic --> store (content / app) or stage (agent) | - | local server 127.0.0.1:8080: SPA, payload, media, status, SSE events, update screen | - | upload server on the service port (10.77.0.1:80): upload page + import API | - | sync: content (backend), release channels, refresh socket; backend WS: telemetry + commands | - +--------------------------------------------------------------------------------------------------+ - | CDP 127.0.0.1:9222 (update screen, reload) | staged agent package - v v - Chromium kiosk (cage) musallahboard-agent-update.service (root, re-verifies) + console (LensBridge) --setup file + content + app + agent .mbu (USB kit)--+ + | + USB stick --> usb-import helper (root, no network, copies *.mbu) --+ | + laptop / phone --HTTP upload on the service port-------------------+ | + sudo musallahboard-agent import -----------------------------------+--> inbox + | + +----------------------- musallahboard-agent (daemon, unprivileged) --+------------------+ + | CORE (internal/core): importer (verify, decide, install / stage agent, apply setup) | + | local server 127.0.0.1:8080 (app, payload, media, status, events, setup/update pages) | + | upload server 10.77.0.1:80, clock, kiosk (CDP, update screen, healer), updates | + | (release channels on GitHub: public, no key) | + | ONLINE (internal/online), only with a backend in agent.toml: claim, content sync, | + | weather, WebSocket (telemetry, commands, content_changed) | + +-----------------------------------------------------------------------------------------+ + | CDP 127.0.0.1:9222 | staged agent package + v v + Chromium kiosk (cage) musallahboard-agent-update.service (root, re-verifies) ``` +| Directory | What | +|---|---| +| `cmd/agent` | the `musallahboard-agent` binary: daemon and CLI | +| `internal/core/...` | the offline board: `mbu`, `trust`, `state`, `store`, `config`, `importer`, `localserver`, `uploadserver`, `events`, `notice`, `clock`, `kiosk`, `usbimport`, `selfupdate`, `updates`, `netinfo`, `fsutil` | +| `internal/online` | the fleet layer: `Layer` (online.go) runs `enroll` (claim, enroll, signing keys), `boardsync`, `wsclient` (with telemetry) and `commands`; `api` is generated from the backend's OpenAPI | +| `internal/version` | the version string set at build time | +| `packaging/` | systemd units, udev rules, sudoers, modules-load, `start-kiosk.sh`, `starting.html`: embedded in the binary, written by `install-system` | +| `update-anim/` | the update screen page, embedded | +| `cmd/mbpack`, `cmd/mbpush`, `vm/mbvm` | package tool, laptop upload tool, QEMU test board | + +**The rule:** nothing under `internal/core` imports anything under +`internal/online` (`internal/core/imports_test.go` fails the build's tests if +it does). The online layer uses the core: it imports packages through the +importer and reports through the local status. + + ## 4. Package format (`.mbu`, format version 2) A zip file. Entries: @@ -123,7 +138,7 @@ Common fields, all required unless noted: |---|---| | `format` | `"mbu"` | | `formatVersion` | `2`. Anything else is rejected. | -| `type` | `"content"`, `"app"` or `"agent"` | +| `type` | `"content"`, `"provision"`, `"app"` or `"agent"` | | `createdAt` | RFC 3339 UTC, second precision. Used as a signed lower bound for the clock (section 10). With an NTP-synchronised clock, a package whose `createdAt` is more than a day ahead of it is refused. | | `files` | Array as above. `sha256` lowercase hex of the file bytes; `bytes` its exact size. Paths unique and valid per the entry-name rules. | @@ -131,13 +146,13 @@ Per type: **`content`** (signed by a *content* key) -- `deviceId`: required, the enrolled device id. Content is always device-bound. +- `deviceId`: required, the board's device id. Content is always device-bound. - `sequence`: required, positive integer, strictly increasing per device. The backend uses the build time in epoch milliseconds (not truncated to seconds, so two builds in the same second still order). - `content.timezone`: IANA zone, not empty, not `Local`, loadable on the board. - `content.firstDay`, `content.lastDay`: `YYYY-MM-DD`, inclusive, first <= last, - at most 31 days. + at most 92 days. - `files` contains exactly one `payloads/.json` for every date in the range and no other payloads; and `media/.` files (ext `[a-z0-9]{1,10}`) whose name hash equals their `sha256`. Nothing else. @@ -151,6 +166,32 @@ Per type: rejects any payload with a `posterUrl` (at any depth) that is not such a path. - Limits: payload file at most 16 MiB; total media at most 512 MiB. +**`provision`**, a *setup file* (signed by a *content* key) + +- `deviceId`: required, the device the file sets the board up as. +- `sequence`: required, positive, strictly increasing per device (the backend + uses the issue time in epoch milliseconds; every download is newer). +- `version`: `null`; no `content`, `app` or `agent` section. +- `files` is exactly one file, `provision.json`, at most 64 KiB: + +```json +{ + "format": 1, + "deviceId": "", + "displayName": "North Musallah", + "sequence": 1700000000000, + "issuedAt": "2026-11-19T12:00:00Z", + "backendUrl": "https://api.example.org", + "claimSecret": "" +} +``` + + `deviceId` and `sequence` must equal the manifest's. `backendUrl` (a plain + http(s) base URL) and `claimSecret` are both present (a board that will go + online) or both absent (an offline-only board). A setup file never carries + keys, software, SSH keys, wifi or anything that runs: the content key may + only ever affect content and identity. How a board applies one: section 9. + **`app`** (signed by a *release* key) - `version`: required, `MAJOR.MINOR.PATCH` (digits only). @@ -188,14 +229,16 @@ verifies, is refused. - `keyId`: lowercase hex of the first 8 bytes of SHA-256 of the raw 32-byte public key. - A package is authentic if at least one signature verifies under a key of the - role its type requires: `content` -> content keys; `app` and `agent` -> - release keys. Signatures by unknown keys are ignored, not errors (rotation). + role its type requires: `content` and `provision` -> content keys; `app` + and `agent` -> release keys. Signatures by unknown keys are ignored, not errors (rotation). - Private keys are stored as the base64 of the 32-byte Ed25519 seed. Public keys are exchanged as base64 of the raw 32 bytes. ### 4.3 File names (convention only; the agent does not parse them) -- `musallahboard-content--.mbu` +- `musallahboard-content--.mbu`, or + `content-.mbu` in a USB kit +- `setup-.mbu` (a setup file, from the console) - `musallahboard-app-.mbu` - `musallahboard-agent--.mbu` @@ -213,7 +256,8 @@ mbpack inspect file.mbu `--key-file` may be replaced by `--key-env NAME` (base64 seed in that environment variable). The frontend repo also carries a dependency-free Node -packer (`scripts/package-mbu.mjs`) producing the same format. +packer (`scripts/package-mbu.mjs`) producing the same format. Content +packages and setup files are made by the backend. ## 5. Trust store @@ -226,20 +270,23 @@ packer (`scripts/package-mbu.mjs`) producing the same format. } ``` -- **Content keys** are pinned at enrollment: `POST /api/agent/enroll` returns - them (`contentSigningKeys`) over the same TLS connection that establishes the - device identity. `sudo musallahboard-agent trust fetch` +- **Content keys** are pinned by `setup.sh`, which asks for LensBridge's + content signing public key (or takes `MB_CONTENT_KEY`) and runs `trust add + content`. A board that never goes online has no other way to get it, and + accepts no content and no setup file without it. `enroll` also pins the + keys its reply carries, and `sudo musallahboard-agent trust fetch` (`GET /api/agent/signing-keys`, over TLS) re-reads them, for example after a - key rotation. + key rotation. The daemon cannot pin keys; when a claim reply names a key + that is not pinned it logs that `trust fetch` is needed. - **Release keys** are compiled into the agent (`-ldflags -X - github.com/LensBridge/agent/internal/trust.BuiltinReleaseKeys=[,]`) + github.com/LensBridge/agent/internal/core/trust.BuiltinReleaseKeys=[,]`) and may be extended in `trust.json`. A dev build without a compiled key accepts only keys in `trust.json`. - `musallahboard-agent trust show|add |remove |fetch` manage it (root). The daemon only reads it. - The root self-updater trusts only `trust.json` and the keys compiled into the binary running as root. Because the daemon can write the directory (it owns - `kiosk-url`), every root reader and writer of `trust.json` refuses a file + `agent.toml` and `agent.key`), every root reader and writer of `trust.json` refuses a file that is not a regular, root-owned, singly linked file writable only by root: a file the daemon planted there is never trusted or carried forward. @@ -251,8 +298,8 @@ packer (`scripts/package-mbu.mjs`) producing the same format. | `/usr/lib/musallahboard/agent.prev` | root 0755 | previous agent, for rollback | | `/usr/lib/musallahboard/update-in-progress.json` | root 0644 | journal of an agent update not yet finished (section 12) | | `/usr/lib/musallahboard/update-strikes.json` | root 0644 | per agent version, updates rolled back only for not reconnecting (section 12) | -| `/etc/musallahboard/agent.toml` | daemon 0600 | config (section 11) | -| `/etc/musallahboard/agent.key` | daemon 0600 | device identity key (unchanged) | +| `/etc/musallahboard/agent.toml` | daemon 0600 | identity and config (section 11); absent on an unprovisioned board | +| `/etc/musallahboard/agent.key` | daemon 0600 | device key, only on a board that claimed or enrolled | | `/etc/musallahboard/trust.json` | root 0644 | trust roots | | `/var/lib/musallahboard/state.json` | daemon | high-water marks and clock floor (below) | | `/var/lib/musallahboard/content/media/.` | daemon | content-addressed media store | @@ -262,11 +309,22 @@ packer (`scripts/package-mbu.mjs`) producing the same format. | `/var/lib/musallahboard/app/current` | daemon | relative symlink to `releases/` | | `/var/lib/musallahboard/agent/staged/` | daemon | `package.mbu` + `ready` for the root updater | | `/var/lib/musallahboard/agent/last-update.json` | root | outcome of the last self-update | -| `/var/lib/musallahboard/inbox/` | daemon 0770 | `*.mbu` dropped by the CLI and USB helper | +| `/var/lib/musallahboard/agent/pending-notice.json` | daemon | the notice of the batch that staged an agent, for the next agent to show | +| `/var/lib/musallahboard/inbox/` | daemon 0770 | `*.mbu` dropped by the CLI and USB helper, `usb-.notice.json` banners, hidden download directories | | `/var/lib/musallahboard/inbox/results/.json` | daemon | outcome per inbox file | | `/var/lib/musallahboard/updates/{agent,app}.mbu` | daemon 0750 | software from the release channels, waiting for its install window (section 9.4) | | `/var/lib/musallahboard/updates/install-now[.result.json]` | daemon | `update now` request from the CLI, and the daemon's answer | +System files, all written by `musallahboard-agent install-system` from the +copies embedded in the binary (`packaging/`): the units in +`/lib/systemd/system` (`musallahboard-agent.service`, +`musallahboard-kiosk.service`, `musallahboard-agent-update.{path,service}`, +`musallahboard-usb-import@.service`, and `musallahboard-rtc.service` with +`--rtc`), `/etc/udev/rules.d/90-musallahboard-{usb,rtc}.rules` (and +`85-musallahboard-rtc.rules`), `/etc/sudoers.d/musallahboard-agent`, +`/etc/modules-load.d/musallahboard.conf`, `/usr/bin/start-kiosk.sh` and +`/usr/share/musallahboard/starting.html`. + The daemon keeps the current and previous content bundle and app release and prunes the rest; media not referenced by a kept bundle is deleted. @@ -284,7 +342,6 @@ prunes the rest; media not referenced by a kept bundle is deleted. High-water marks live here, not only in the installed directories, so deleting a bundle cannot reopen a rollback. Written atomically (tmp, fsync, rename). - ## 7. Local kiosk API (`127.0.0.1:8080`, local API version 2) Loopback only. `GET`/`HEAD` only; anything else is `405`. All JSON errors are @@ -292,13 +349,14 @@ Loopback only. `GET`/`HEAD` only; anything else is `405`. All JSON errors are | Path | Behaviour | |---|---| -| `/api/musallah/payload` | Today's payload from the current content bundle, verbatim (plus the weather overlay). No content: `503 {"message":"no content installed"}`. `Cache-Control: no-store`. | +| `/api/musallah/payload` | Today's payload from the current content bundle, with three top-level keys set by the agent: `lastDay` (the bundle's), `expired` (`true` once today is past `lastDay`, when the last day's payload is what is served) and, online, the weather overlay. No content: `503 {"message":"no content installed"}`. `Cache-Control: no-store`. | | `/api/local/status` | Status object below. `no-store`. | | `/api/local/events` | Server-Sent Events, below. | +| `/api/local/where` | `{"where":" · "}`, the setup screen's address line. The setup screen refetches it every 10 s, so a later DHCP lease or cable shows up. `Cache-Control: no-store`. | | `/api/*` (other) | `404` JSON, never the SPA. | | `/media/.` | From the media store, if the name is valid and the file exists. `Content-Type` from the current bundle's manifest when listed there, else by extension. `Cache-Control: public, max-age=31536000, immutable`. | | `/_mb/updating` | The update screen (`update-anim/index.html`, embedded in the agent). `no-store`. | -| anything else | Static file from the current app release. Unknown paths fall back to `index.html` (`no-cache`); `/assets/*` is immutable, and a missing `/assets/*` file is `404`. No app installed: the agent's built-in "board app not installed" page, `503`. | +| anything else | On an unprovisioned board: the built-in setup screen ("This board is not set up yet. Plug in its setup USB stick.", the board's hostname and addresses for a maintainer, the import banners from `/api/local/events`), which reloads once the board has a device id. Otherwise a static file from the current app release. Unknown paths fall back to `index.html` (`no-cache`); `/assets/*` is immutable, and a missing `/assets/*` file is `404`. No app installed: the agent's built-in "board app not installed" page, `503`. | **Weather overlay.** Content packages carry `weather: null`. When the board is online, the sync loop fetches `GET /api/agent/weather` (device-authenticated, @@ -317,6 +375,7 @@ the bundle's `timezone`; serve `firstDay` if `today < firstDay`, `lastDay` if "localApi": 2, "agentVersion": "0.3.0", "deviceId": "3f2a…", + "displayName": "North Musallah", "app": { "version": "2.1.0" }, "content": { "sequence": 1790258531000, "createdAt": "2026-09-24T14:02:11Z", @@ -335,7 +394,9 @@ the bundle's `timezone`; serve `firstDay` if `today < firstDay`, `lastDay` if } ``` -`app` and `content` are `null` when nothing is installed; `servingDay`, +`deviceId` is `""` on an unprovisioned board, and `displayName` is absent +when its setup file has none. `app` and `content` are `null` when nothing is +installed; `servingDay`, `daysRemaining` and `staleDays` are then `null` and `today` is in the system zone. `source` is one of `sync`, `usb`, `upload`, `cli`. `sync.lastError` is a short human string or `null`. If installed content cannot be read, `content` is @@ -372,10 +433,10 @@ One importer in the daemon serialises every install. Sources: `sync`, `usb`, Per package: 1. **Verify** in a private staging directory: zip rules, manifest schema, - signature by the right role, type rules (section 4), and for content the - device id. A content package for another device is reported as `skipped` - ("for another board"), not as a failure: one USB stick can serve many - boards. + signature by the right role, type rules (section 4), and for content and + setup files the device id. A content package or setup file for another + device is reported as `skipped` ("for another board"), not as a failure: + one USB stick can serve many boards. 2. **Decide** against `state.json`: newer -> install; equal -> `unchanged`; older -> `outdated` ("The board already has newer content"). Neither is a failure: an old USB stick at a board that synced since is the normal case. @@ -388,13 +449,15 @@ Per package: record the version, prune, emit `app`. - agent: write the verified package to `agent/staged/package.mbu` and create `agent/staged/ready`. The root updater does the rest (section 12). + - provision: write `agent.toml` (section 9.8). 4. **Clock**: every verified package raises `clockFloor` to its `createdAt` (section 10). With NTP synchronised, a `createdAt` more than a day ahead of the clock is refused before anything is recorded ("An update is dated in the future: the computer that made it has a wrong clock"), and one less than a day ahead raises the floor only to NTP time. -A batch processes `agent` packages first, then `app`, then `content`. When an +A batch processes setup files first (they decide which board this is, and so +which content is for it), then `agent`, `app` and `content`. When an agent package is staged, the rest of the batch stays in the inbox and is processed by the new agent after the restart. @@ -442,11 +505,11 @@ Results are JSON objects per package: ### 9.1 Online: backend content sync -The daemon, when `content_sync` is on and the board is enrolled: +The online layer (section 9.8), when `content_sync` is on: -- syncs at startup, every 30 minutes, and 10 s after any message on the - backend's refresh channel (`wss:///api/refresh-musallahboard?deviceId=`, - debounced), +- syncs at startup, every 30 minutes, and 10 s plus up to 20 s of jitter + after a `{"type":"content_changed"}` frame on the agent WebSocket (or the + `config.refresh` command); requests before that sync fold into it, - with `POST /api/agent/content-bundle`, device-authenticated (9.2), body `{"days": , "haveMedia": ["", ...]}`, - and imports the returned package with source `sync`. @@ -497,8 +560,11 @@ in front of still says what it runs, what it shows, and what is wrong. | `POST /api/agent/content-bundle` | device (9.2) | `200 application/vnd.musallahboard.mbu` signed content package. `503` if no content signing key is configured. | | `GET /api/agent/weather` | device (9.2) | `{"weather": or null, "fetchedAt": ""}`. Never a 5xx for missing weather: `weather` is `null`. | | `GET /api/agent/signing-keys` | none | `{"content": [{"keyId", "publicKey"}]}` | -| `POST /api/agent/enroll` | token | unchanged, plus `contentSigningKeys: [{"keyId", "publicKey"}]` | +| `POST /api/agent/enroll` | token | `{deviceId, websocketUrl, contentSigningKeys: [{"keyId", "publicKey"}]}` | +| `POST /api/agent/claim` | claim proof (9.8) | the same as enroll; `409` when the device already has another key | | `GET /api/admin/board/devices/{id}/offline-bundle?days=14` | `BOARD_DEVICE_READ` | the signed `.mbu` (filename `musallahboard-content--.mbu`), media always included | +| `GET /api/admin/board/devices/{id}/setup-file[?online=true]` | admin | the board's signed setup file; `online=true` includes `backendUrl` and a freshly rotated claim secret | +| `GET /api/admin/board[/devices/{id}]/usb-kit?days=N` | admin | a zip with one `MusallahBoard/` folder: setup files (with `includeSetup=true`), content packages, the latest board app and arm64 agent | Backend configuration: `musallahboard.content-signing.private-key` (base64 seed; env `MUSALLAHBOARD_CONTENT_SIGNING_KEY`), and optionally @@ -507,7 +573,9 @@ still published in `signing-keys` during a rotation. ### 9.4 Online: release channels -When `auto_update` is on, the daemon checks every 6 hours (and 2 minutes after +Any board with a network follows them, provisioned and enrolled or not: the +channels are public files, and what they point at is verified against the +release keys. When `auto_update` is on, the daemon checks every 6 hours (and 2 minutes after start) two channel URLs. A failed check (usually a board with no internet) is retried after 5 minutes, then 10, 20 and so on up to 6 hours, so the error clears soon after the network returns. Each channel fetch gives up after 30 @@ -589,9 +657,12 @@ folder on it, and plug it into the board. - `musallahboard-agent usb-import ` checks the name (`^sd[a-z]+[0-9]*$`), reads the type with `blkid` and allows only `vfat`, `exfat`, `ext4`, `ntfs3`/`ntfs`; mounts it at `/run/musallahboard/usb/` - with `ro,nosuid,nodev,noexec,noatime`; copies at most 16 regular files (no - symlinks) named `*.mbu`, each at most 512 MiB, into the inbox; unmounts; then - waits up to 15 minutes for the daemon's results and logs them. + with `ro,nosuid,nodev,noexec,noatime`; copies at most 64 regular files (no + symlinks) named `*.mbu`, each at most 512 MiB and together at most 4 GiB, + into the inbox; unmounts; then waits up to 15 minutes for the daemon's + results and logs them. It reads sticks on an unprovisioned board too. It + parses nothing on the stick: a USB kit for 20 boards (42 files) is copied + whole, and each board skips the packages for other boards. - The helper tells the board what it is doing through banners: it drops a notice in the inbox (`inbox/usb-.notice.json`) that the daemon shows. "Reading USB stick" as soon as the stick is seen; then either the batch's @@ -617,6 +688,64 @@ channels and install a new app or agent at once (section 9.4), and prints the results. `musallahboard-agent status` shows what is waiting and when it installs. + +`sudo musallahboard-agent install-system [--rtc]` writes the system files +embedded in the agent (section 6) where they belong, removes files earlier +versions installed (`musallahboard-kiosk-watch.path`, +`musallahboard-kiosk-reload.service`, `kiosk-url`, `waiting.html`), reloads +systemd and udev and enables the units. It is idempotent; setup.sh runs it. + +`sudo musallahboard-agent enroll --token=T --backend=URL` binds a device key +with a one-time token (the maintainer path, and how a board whose SD card was +replaced gets a new key bound to its existing device). It keeps the board's +other settings and restarts the agent. + +### 9.8 Setup files and the online layer + +**Applying a setup file** (`internal/core/importer/provision.go`), from any +transport: + +- an unprovisioned board adopts any valid setup file's `deviceId` and + `displayName`, unless the batch holds setup files for more than one device + (a USB kit), when it takes none and says "This USB stick sets up more than + one board"; +- a provisioned board takes a file only for its own `deviceId` with a + strictly newer `sequence` (same: `unchanged`, older: `outdated`), updating + its name and, if the file has one, its backend and claim secret; a new + backend clears `websocket_url`, so the board claims there. A file for + another device is `skipped`. A file without a backend never removes one. +- It is written to `agent.toml` (`device_id`, `display_name`, + `provision_sequence`, `backend_url`, `claim_secret`) in one atomic save by + the daemon, which owns that file: a root step would guard nothing the + daemon could not already write. Content in the same batch then binds to the + new identity. + +**The online layer** (`internal/online.Layer`) runs only when `agent.toml` has +`device_id` and `backend_url`, and starts over whenever those settings change. + +- Without `websocket_url` but with `claim_secret`, it **claims**: it makes the + Ed25519 device key if there is none (saved before it is first sent, so a + retry claims the same key; the private key never leaves the board), checks + the backend URL is https, and sends + + ``` + POST /api/agent/claim + {"deviceId", "publicKey": , "proof", "agentVersion", "hostname"} + proof = base64url (unpadded) of HMAC-SHA256(key = claim secret bytes, + message = deviceId + "\n" + publicKey) + ``` + + The reply has the enrollment reply's shape; its `websocketUrl` must be wss + on the backend's host. It is saved and the secret dropped, and the layer + starts over online. Failures retry from 1 minute, doubling to an hour; a + `409` (another key is bound: an SD card was replaced) is logged and shown + in the status, and fixed with a new device-bound token (`enroll --token`). +- With `websocket_url` and a readable `agent.key`, it runs content sync, + weather and the WebSocket with telemetry, the board report and commands, + exactly as an enrolled board always has. +- A config that fails the transport check (section 11) runs none of it; the + reason is in the log and the status. + ## 10. Clock Correct time decides which day's content is shown and the prayer times, and @@ -683,31 +812,33 @@ minutes off. ## 11. Configuration (`/etc/musallahboard/agent.toml`) -Existing keys (`device_id`, `backend_url`, `websocket_url`, `key_path`) are -unchanged, with one rule (`config.CheckTransport`): `backend_url` must be -`https://` and `websocket_url` `wss://` on the same host as `backend_url` (the -port may differ: TLS binds the host name, not the port; there is no override -for a socket on another host). `enroll` checks the backend URL before it sends -the token and the returned WebSocket URL before it saves anything, and the -daemon checks both at every start. A config that fails is still read, so the -board keeps showing what it has and the local CLI keeps working, but nothing -that talks to the backend is started (content sync, refresh channel, release -checks, the command WebSocket); the reason goes to the log, `systemctl status` -and the `sync`/backend errors in `/api/local/status`. New keys, all optional: - -| Key | Default | Meaning | +Every key is optional; a board without the file is unprovisioned. One rule +(`config.CheckTransport`): `backend_url` must be `https://` and +`websocket_url` `wss://` on the same host (the port may differ). `enroll` and +the claim check the backend URL before they send anything and the returned +WebSocket URL before they save it, and the online layer checks both every +time it starts. A config that fails is still read, so the board keeps showing +what it has and the local CLI keeps working, but nothing that talks to the +backend runs. + +| Key | Written by | Meaning | |---|---|---| -| `service_port` | `false` | Run the eth0 service port and the upload server. Set by `musallahboard-agent service-port on|off`. | -| `usb_import` | `true` | Accept USB sticks. | -| `content_sync` | `true` | Sync content from the backend. | -| `content_days` | `7` | Days per synced content package (1-31). | -| `auto_update` | `true` | Follow the release channels. | -| `app_channel_url`, `agent_channel_url` | section 9.4 | Channel pointers. Empty disables that channel. | -| `update_time` | `"23:00"` | When software from the channels installs, `HH:MM` in the board's time zone (section 9.4). | -| `insecure_dev` | `false` | Development boards only: allow `http://` and `ws://` (the same-host rule still applies). Set by `enroll --insecure-dev`; the daemon logs a warning at every start while it is on. | - -An offline board needs no configuration change: sync attempts fail fast with no -route and cost nothing, and the moment it gets a network it starts syncing. +| `device_id`, `display_name`, `provision_sequence` | setup file, `enroll` | the board's identity | +| `backend_url` | setup file, `enroll` | the online layer's backend | +| `claim_secret` | setup file | until the claim succeeds | +| `websocket_url` | claim, `enroll` | the agent WebSocket; its presence means "key bound" | +| `service_port` (`false`) | `service-port on\|off` | run the eth0 service port and the upload server | +| `usb_import` (`true`) | by hand | accept USB sticks | +| `content_sync` (`true`) | by hand | sync content from the backend | +| `content_days` (`7`) | by hand | days per synced content package (1-92) | +| `auto_update` (`true`) | by hand | follow the release channels | +| `app_channel_url`, `agent_channel_url` | by hand | channel pointers (section 9.4); empty disables one | +| `update_time` (`"23:00"`) | by hand | when channel software installs, `HH:MM` in the board's zone | +| `insecure_dev` (`false`) | `enroll --insecure-dev` | development boards only: allow `http://` and `ws://` (same host); warned about at every start | + +The device key is always `/etc/musallahboard/agent.key`; `key_path` in older +files is ignored. The file is written atomically and given the owner of +`/etc/musallahboard` (the service user), also when root tools write it. ## 12. Agent self-update @@ -733,8 +864,7 @@ route and cost nothing, and the moment it gets a network it starts syncing. `active`) for 4 minutes; and if the board was connected before the update (`backend.connected`, or `sync.lastSuccessAt` with no `lastError`), it must connect again within 3 minutes. A board that was offline is not - asked to be online. If it passes, the outcome is written and the - enrollment splash refreshed (`splash install`). + asked to be online. If it passes, the outcome is written. 5. If it fails, the updater restores `agent.prev`, records the outcome in `agent/last-update.json`, and only then restarts the previous agent, so it can read it. Not coming up, a restart or crash loop, or a probation cut @@ -761,7 +891,7 @@ format only ever gains fields. What it does: | `swapping` | previous | the swap never happened: removes the extracted binary, outcome `refused` ("interrupted"), nothing else changes | | `swapping` or `probation` | new | starts the probation again from scratch, without restarting the agent; after 3 cut-short probations, rolls back and rejects | | `swapping` or `probation` | anything else | someone installed another agent: left alone, outcome `refused` | -| `committing` | | writes the `ok` outcome again (same timestamp), refreshes the splash, removes the journal | +| `committing` | | writes the `ok` outcome again (same timestamp), removes the journal | | `rolling-back` | | repeats the rollback: restores `agent.prev` if it is not in place, rejects or strikes (idempotent), writes the outcome, removes the journal, restarts the agent | | unreadable | | puts `agent.prev` back if it differs, outcome `rolled-back` | @@ -775,8 +905,7 @@ one that does not is resumed as above. Not covered: a new agent that starts crashing after its probation is restarted by systemd for ever (with a growing delay) and is not rolled -back. Safe mode (`internal/safemode`) only reports such a board, as -`safeMode` in its heartbeats; it does not change what the agent does. +back. Telling the people at the board (`internal/agentupdate`): the agent that staged the package leaves the screen on "Restarting MusallahBoard" and its @@ -811,48 +940,36 @@ connecting a board to a network permanently. ## 14. Kiosk -- `kiosk-url` is `http://127.0.0.1:8080/` once enrolled (no query string; the - page asks the agent who it is). Before enrollment it is absent and the - `waiting.html` splash shows. The splash is embedded in the agent - (`packaging/waiting.html`) and written by `musallahboard-agent splash - install`, which setup.sh runs and the self-updater re-runs after each - update; the agent pushes the address and its own version into it over CDP. +- `start-kiosk.sh` always opens `starting.html#http://127.0.0.1:8080/`. + `starting.html` (a local page, written by `install-system`) loads + `/_mb/alive.gif` from the agent every 2 s and moves to the board once that + answers, so Chromium never shows its own "refused to connect" page while + the agent starts or restarts. There is no other kiosk URL: an + unprovisioned board's setup screen is served at the same address. - `musallahboard-kiosk.service` is ordered `After=` and `Wants=` `musallahboard-agent.service`, and the agent reports `READY=1` only after the - local server is listening, so Chromium never starts before the server. -- On an enrolled board the kiosk opens `starting.html` (a local page, embedded - in the agent with `waiting.html`) with the board's URL in its fragment. It - loads `/_mb/alive.gif` from the agent every 2 s and moves to the board once - that answers, so Chromium never shows its own "refused to connect" page - while the agent starts or restarts. + local server is listening. - The agent's unit never gives up restarting (`StartLimitIntervalSec=0`); a crash loop backs off from 5 s to 2 minutes (`RestartSteps`, `RestartMaxDelaySec`, systemd 254 and later). - systemd's watchdog (`WatchdogSec=60s`) restarts an agent that is alive but - stuck. The agent pings only while a heartbeat is fresh: before enrollment - its poll loop bumps it, once enrolled a probe of its own + stuck. The agent pings only while a heartbeat is fresh: a probe of its own `/api/local/status` every 10 s (the local server and the locks of the sync, - backend, update and clock state). A heartbeat older than 60 s withholds - the ping, so a stuck agent is restarted within about 2 minutes. The probe - never waits on the network, so an offline board is not restarted for it; - a stall in the network loops themselves is not detected. -- The daemon still watches for Chromium's error page and navigates back to the - board, as a backstop. -- Every 30 s it also probes the page over CDP: `Inspector.enable` (which - Chromium answers with `Inspector.targetCrashed` when the tab's renderer is - gone, "Aw, Snap!") and a trivial `Runtime.evaluate` with a 5 s limit. A - crashed page (one probe) or one that has not answered three probes in a row - is reloaded; if it is still dead at the next threshold the kiosk unit is - restarted (`sudo -n systemctl restart`, as the `kiosk.restart` command). - Restarts are at least 5 minutes apart, doubling to an hour, and the backoff - starts over only after an hour of a healthy page. A reload is tried at most - once until the page answers again or the kiosk restarts. Nothing is done - while the update screen is up, nor for a page that answers without the - board's `getStatus()` hook (splash, update screen, an old board app), a page - mid-navigation, or a browser that is not up yet. -- The heartbeat's `kioskAlive` comes from the same probe: false when the - browser is reachable but the page crashed or does not answer; the unit's - state is used only when the browser cannot be reached. + backend, update and clock state). A heartbeat older than 60 s withholds the + ping, so a stuck agent is restarted within about 2 minutes. The probe never + waits on the network, so an offline board is not restarted for it. +- `internal/core/kiosk` watches Chromium every 30 s: it navigates back from + Chromium's error page, and probes the page over CDP (`Inspector.enable`, + which reports a crashed renderer, and a trivial `Runtime.evaluate` with a + 5 s limit). A crashed page (one probe) or one that has not answered three + probes in a row is reloaded; if it is still dead at the next threshold the + kiosk unit is restarted (`sudo -n systemctl restart`, as the + `kiosk.restart` command). Restarts are at least 5 minutes apart, doubling + to an hour; the backoff starts over after an hour of a healthy page. + Nothing is done while the update screen is up, nor for a page without the + board's `getStatus()` hook (setup screen, update screen, an old board app), + a page mid-navigation, or a browser that is not up yet. +- The heartbeat's `kioskAlive` comes from the same probe. ## 15. Frontend (MusallahBoard) @@ -866,6 +983,11 @@ per-day payloads from installed content, and weather comes through the agent. - No content yet: a clear "waiting for content" screen that says whether the board is syncing (with the last error) or needs a USB stick / upload. - Stale content: the "Content last updated ..." note when `staleDays > 0`. +- Run-out: when the payload says `expired`, prayer times (computed for + today) and a calm "Announcements are out of date, plug in an update stick" + note; posters, agenda and dated items are hidden. Never a blank screen. +- An unprovisioned board never shows the app: the agent serves its setup + screen instead (section 7). - Diagnostics (Alt+Shift+F) show agent and app versions, content range and source, days remaining, sync status. - Waiting software updates (`updates` in the status) add "Update available: @@ -883,6 +1005,9 @@ per-day payloads from installed content, and weather comes through the agent. | Threat | Mitigation | |---|---| | Malicious content via any transport | Content must be signed by a pinned content key and bound to this device id. | +| A setup file from someone else | Signed by a pinned content key, never unsigned. A provisioned board takes only its own device id with a newer sequence; another identity means reflashing. A setup file can only name a device and a backend: no keys, software or anything that runs. Whoever holds the content key can set up a blank board, the same power as content. | +| Several setup files on one stick | An unprovisioned board takes none of them. | +| A stolen claim secret | It only binds a key to a device that has none; a device with a key answers 409. The console rotates it with every online setup file. | | Malicious code (SPA or agent) | Only the release key signs software; the backend never holds it. | | Backend compromise | Limited to content on screens; cannot push code. Content key rotation via `previous-public-keys` and `trust` CLI. | | Replay of old packages | Monotonic sequence/version in `state.json`. | @@ -893,7 +1018,7 @@ per-day payloads from installed content, and weather comes through the agent. | Rogue DHCP on a building network | Service port only after a DHCP client attempt fails; off by default; `service-port off` before connecting. | | Clock tampering | With NTP, nothing but NTP moves the clock, and a floor ahead of NTP time is lowered. Without NTP, the clock only moves forward to the floor automatically; uploader time only with a verified package and within 90 days past the floor, and never into the floor. Packages signed more than a day ahead of an NTP clock are refused. | | DNS rebinding against the upload server | `Host` allow-list. | -| Enrollment or backend impersonated on the LAN | `https://` backend and `wss://` socket on the backend's host, enforced at enrollment and at every daemon start; plaintext only with the explicit `insecure_dev` opt-in (section 11). | +| Enrollment, claim or backend impersonated on the LAN | `https://` backend and `wss://` socket on the backend's host, enforced before an enrollment or claim is sent, on its reply, and at every start of the online layer; plaintext only with the explicit `insecure_dev` opt-in (section 11). | ## 17. Out of scope @@ -901,3 +1026,5 @@ per-day payloads from installed content, and weather comes through the agent. overlay in section 7). - Automatic eth0 switching between service port and LAN. - Release key rotation other than shipping a new agent with an added key. +- Wifi: a maintainer joins a network over SSH if a board needs one. +- Clock: beyond the floor and an optional RTC (section 10). diff --git a/internal/boardsync/boardsync_test.go b/internal/boardsync/boardsync_test.go deleted file mode 100644 index cb2ca1e..0000000 --- a/internal/boardsync/boardsync_test.go +++ /dev/null @@ -1,624 +0,0 @@ -package boardsync - -import ( - "bytes" - "context" - "crypto/ed25519" - "crypto/sha256" - "encoding/base64" - "encoding/hex" - "encoding/json" - "io" - "net/http" - "net/http/httptest" - "os" - "path/filepath" - "runtime" - "strconv" - "strings" - "sync" - "sync/atomic" - "testing" - "time" - - "github.com/coder/websocket" - - "github.com/LensBridge/agent/internal/config" - "github.com/LensBridge/agent/internal/devauth" - "github.com/LensBridge/agent/internal/importer" - "github.com/LensBridge/agent/internal/mbu" - "github.com/LensBridge/agent/internal/state" - "github.com/LensBridge/agent/internal/store" - "github.com/LensBridge/agent/internal/trust" - "github.com/LensBridge/agent/internal/updates" -) - -const testDevice = "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b" - -func seedKey(b byte) ed25519.PrivateKey { - return ed25519.NewKeyFromSeed(bytes.Repeat([]byte{b}, 32)) -} - -var ( - contentKey = seedKey(1) - releaseKey = seedKey(2) - deviceKey = seedKey(3) -) - -type env struct { - layout store.Layout - cfg *config.Config - syncer *Syncer - updates *updates.Scheduler -} - -func strp(s string) *string { return &s } -func boolp(b bool) *bool { return &b } - -// newEnv builds a Syncer over a temp store with a real importer that trusts -// contentKey and releaseKey. Channels are disabled unless a test sets them. -func newEnv(t *testing.T, backend string) *env { - t.Helper() - l := store.Layout{Root: t.TempDir()} - cfg := &config.Config{ - DeviceID: testDevice, - BackendURL: backend, - WebSocketURL: "ws://unused/api/agent/ws", - AppChannelSet: strp(""), - AgentChannelSet: strp(""), - } - ring := trust.NewRing( - []ed25519.PublicKey{contentKey.Public().(ed25519.PublicKey)}, - []ed25519.PublicKey{releaseKey.Public().(ed25519.PublicKey)}, - ) - im := importer.New(importer.Deps{ - Layout: l, - DeviceID: testDevice, - AgentVersion: "0.3.0", - Ring: func() (*trust.Ring, error) { return ring, nil }, - }) - u := updates.New(updates.Deps{Layout: l, Importer: im, Hour: 23}) - s := New(Deps{Cfg: cfg, Key: deviceKey, Layout: l, Importer: im, Updates: u, AgentVersion: "0.3.0"}) - return &env{layout: l, cfg: cfg, syncer: s, updates: u} -} - -func build(t *testing.T, m mbu.Manifest, src []mbu.Source, key ed25519.PrivateKey) []byte { - t.Helper() - var buf bytes.Buffer - if err := mbu.Build(&buf, m, src, []ed25519.PrivateKey{key}); err != nil { - t.Fatalf("Build: %v", err) - } - return buf.Bytes() -} - -func contentPackage(t *testing.T, seq int64) []byte { - m := mbu.Manifest{ - Type: mbu.TypeContent, Sequence: seq, DeviceID: testDevice, - Content: &mbu.ContentInfo{Timezone: "America/Toronto", FirstDay: "2026-09-24", LastDay: "2026-09-25"}, - } - src := []mbu.Source{ - {Path: "payloads/2026-09-24.json", Data: []byte(`{"frames":[],"weather":null}`)}, - {Path: "payloads/2026-09-25.json", Data: []byte(`{"frames":[],"weather":null}`)}, - } - return build(t, m, src, contentKey) -} - -func appPackage(t *testing.T, version string) []byte { - m := mbu.Manifest{Type: mbu.TypeApp, Version: version, App: &mbu.AppInfo{LocalAPI: 2}} - return build(t, m, []mbu.Source{{Path: "index.html", Data: []byte("" + version)}}, releaseKey) -} - -func agentPackage(t *testing.T, version string) []byte { - m := mbu.Manifest{Type: mbu.TypeAgent, Version: version, - Agent: &mbu.AgentInfo{Arch: runtime.GOARCH, Binary: "musallahboard-agent"}} - return build(t, m, []mbu.Source{{Path: "musallahboard-agent", Data: []byte("#!/bin/sh\necho " + version)}}, releaseKey) -} - -func TestSyncContentSignedAndImported(t *testing.T) { - pkg := contentPackage(t, 1000) - var gotBody struct { - Days int `json:"days"` - HaveMedia []string `json:"haveMedia"` - } - haveSHA := strings.Repeat("ab", 32) - srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - if r.Method != http.MethodPost || r.URL.Path != "/api/agent/content-bundle" { - t.Errorf("unexpected %s %s", r.Method, r.URL.Path) - } - body, _ := io.ReadAll(r.Body) - if err := json.Unmarshal(body, &gotBody); err != nil { - t.Errorf("body: %v", err) - } - if r.Header.Get(devauth.HeaderDeviceID) != testDevice { - t.Errorf("device id header = %q", r.Header.Get(devauth.HeaderDeviceID)) - } - ts, err := strconv.ParseInt(r.Header.Get(devauth.HeaderTimestamp), 10, 64) - if err != nil || time.Since(time.UnixMilli(ts)).Abs() > time.Minute { - t.Errorf("timestamp header = %q", r.Header.Get(devauth.HeaderTimestamp)) - } - sig, _ := base64.StdEncoding.DecodeString(r.Header.Get(devauth.HeaderSignature)) - msg := devauth.Message(r.Method, r.URL.Path, testDevice, ts, body) - if !ed25519.Verify(deviceKey.Public().(ed25519.PublicKey), msg, sig) { - t.Error("signature does not verify over the received body") - } - if !strings.HasSuffix(string(msg), hexSHA(body)) { - t.Error("message does not end in the body hash") - } - w.Header().Set("Content-Type", "application/vnd.musallahboard.mbu") - w.Write(pkg) - })) - defer srv.Close() - - e := newEnv(t, srv.URL+"/") - // A media file already in the store must be offered as haveMedia. - os.MkdirAll(e.layout.MediaDir(), 0o750) - os.WriteFile(filepath.Join(e.layout.MediaDir(), haveSHA+".png"), []byte("x"), 0o640) - - if err := e.syncer.SyncContent(context.Background()); err != nil { - t.Fatalf("SyncContent: %v", err) - } - if gotBody.Days != 7 { - t.Errorf("days = %d, want 7", gotBody.Days) - } - if len(gotBody.HaveMedia) != 1 || gotBody.HaveMedia[0] != haveSHA { - t.Errorf("haveMedia = %v", gotBody.HaveMedia) - } - c, err := e.layout.CurrentContent() - if err != nil || c.Manifest.Sequence != 1000 || c.Info.Source != "sync" { - t.Fatalf("installed content = %+v, %v", c, err) - } - st := e.syncer.Status() - if !st.Enabled || st.LastSuccessAt == nil || st.LastAttemptAt == nil || st.LastError != nil { - t.Errorf("status = %+v", st) - } - if left, _ := filepath.Glob(filepath.Join(e.layout.Inbox(), ".sync-*")); len(left) != 0 { - t.Errorf("download dirs left behind: %v", left) - } - // The same package again is "unchanged", which is still a success. - if err := e.syncer.SyncContent(context.Background()); err != nil { - t.Fatalf("second SyncContent: %v", err) - } -} - -func hexSHA(b []byte) string { - s := sha256.Sum256(b) - return hex.EncodeToString(s[:]) -} - -func TestSyncContentErrors(t *testing.T) { - cases := []struct { - status int - body string - want string - }{ - {503, `{"message":"no content signing key configured"}`, "backend returned 503: no content signing key configured"}, - {401, `{"message":"unknown device"}`, "revoked, or the board's clock is wrong"}, - {500, `oops`, "backend returned 500"}, - } - for _, tc := range cases { - t.Run(strconv.Itoa(tc.status), func(t *testing.T) { - srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - w.Header().Set("Content-Type", "application/json") - w.WriteHeader(tc.status) - io.WriteString(w, tc.body) - })) - defer srv.Close() - e := newEnv(t, srv.URL) - err := e.syncer.SyncContent(context.Background()) - if err == nil || !strings.Contains(err.Error(), tc.want) { - t.Fatalf("err = %v, want %q", err, tc.want) - } - st := e.syncer.Status() - if st.LastError == nil || *st.LastError != err.Error() || st.LastSuccessAt != nil { - t.Errorf("status = %+v", st) - } - }) - } -} - -func TestSyncContentUnreachable(t *testing.T) { - srv := httptest.NewServer(http.NotFoundHandler()) - url := srv.URL - srv.Close() - e := newEnv(t, url) - err := e.syncer.SyncContent(context.Background()) - if err == nil || err.Error() != "backend unreachable" { - t.Fatalf("err = %v", err) - } -} - -func TestSyncContentRejectedPackage(t *testing.T) { - // Signed by the release key: authentic to nobody for content. - m := mbu.Manifest{Type: mbu.TypeContent, Sequence: 5, DeviceID: testDevice, - Content: &mbu.ContentInfo{Timezone: "UTC", FirstDay: "2026-09-24", LastDay: "2026-09-24"}} - pkg := build(t, m, []mbu.Source{{Path: "payloads/2026-09-24.json", Data: []byte(`{}`)}}, releaseKey) - srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.Write(pkg) })) - defer srv.Close() - e := newEnv(t, srv.URL) - err := e.syncer.SyncContent(context.Background()) - if err == nil || !strings.Contains(err.Error(), "refused") { - t.Fatalf("err = %v", err) - } -} - -func TestContentBackoff(t *testing.T) { - var hits atomic.Int32 - srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - if r.URL.Path == "/api/agent/content-bundle" { - hits.Add(1) - } - w.WriteHeader(503) - })) - defer srv.Close() - e := newEnv(t, srv.URL) - s := e.syncer - s.minBackoff, s.maxBackoff = 20*time.Millisecond, 80*time.Millisecond - s.contentInterval = time.Hour - ctx, cancel := context.WithTimeout(context.Background(), 330*time.Millisecond) - defer cancel() - s.contentLoop(ctx) - // Attempts at about 0, 20, 60, 140, 220, 300 ms: doubling, then capped. - if n := hits.Load(); n < 4 || n > 8 { - t.Fatalf("%d attempts in 330 ms, want about 6", n) - } -} - -func TestRefreshTriggersDebouncedSync(t *testing.T) { - pkg := contentPackage(t, 1000) - var hits atomic.Int32 - var mu sync.Mutex - var sockets []*websocket.Conn - srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - switch r.URL.Path { - case "/api/agent/content-bundle": - hits.Add(1) - w.Write(pkg) - case "/api/refresh-musallahboard": - if r.URL.Query().Get("deviceId") != testDevice { - t.Errorf("refresh deviceId = %q", r.URL.Query().Get("deviceId")) - } - c, err := websocket.Accept(w, r, nil) - if err != nil { - return - } - mu.Lock() - sockets = append(sockets, c) - mu.Unlock() - // Three messages in quick succession fold into one sync. - for range 3 { - c.Write(r.Context(), websocket.MessageText, []byte("refresh")) - } - c.Read(r.Context()) // hold open until the client goes - default: - http.NotFound(w, r) - } - })) - defer srv.Close() - e := newEnv(t, srv.URL) - e.syncer.triggerDelay = 50 * time.Millisecond - ctx, cancel := context.WithCancel(context.Background()) - done := make(chan struct{}) - go func() { e.syncer.Run(ctx); close(done) }() - // Wait for the second sync rather than giving the whole exchange a fixed - // budget: under -race on a busy CI runner, start-up sync, WebSocket dial - // and debounce together can take longer than any small constant. - deadline := time.Now().Add(10 * time.Second) - for hits.Load() < 2 && time.Now().Before(deadline) { - time.Sleep(10 * time.Millisecond) - } - // Then long enough for any extra, unfolded sync to show up. - time.Sleep(10 * e.syncer.triggerDelay) - cancel() - <-done - mu.Lock() - for _, c := range sockets { - c.CloseNow() - } - mu.Unlock() - // One at start, one for the burst of refresh messages. - if n := hits.Load(); n != 2 { - t.Fatalf("%d content syncs, want 2", n) - } -} - -func TestRefreshURL(t *testing.T) { - for in, want := range map[string]string{ - "https://api.example": "wss://api.example/api/refresh-musallahboard?deviceId=" + testDevice, - "http://10.0.0.2:8080/": "ws://10.0.0.2:8080/api/refresh-musallahboard?deviceId=" + testDevice, - "https://api.example/base/": "wss://api.example/base/api/refresh-musallahboard?deviceId=" + testDevice, - } { - got, err := refreshURL(in, testDevice) - if err != nil || got != want { - t.Errorf("refreshURL(%q) = %q, %v; want %q", in, got, err, want) - } - } - if _, err := refreshURL("ftp://x", testDevice); err == nil { - t.Error("ftp scheme accepted") - } -} - -func TestWeather(t *testing.T) { - body := `{"weather":{"tempC":12,"icon":"sun"},"fetchedAt":"2026-09-24T12:00:00Z"}` - srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - if r.URL.Path != "/api/agent/weather" || r.Method != http.MethodGet { - t.Errorf("unexpected %s %s", r.Method, r.URL) - } - if r.Header.Get("X-MB-Device-Id") != testDevice || r.Header.Get("X-MB-Signature") == "" { - t.Errorf("weather request is not device-signed: %v", r.Header) - } - io.WriteString(w, body) - })) - defer srv.Close() - e := newEnv(t, srv.URL) - s := e.syncer - now := time.Date(2026, 9, 24, 12, 0, 0, 0, time.UTC) - s.now = func() time.Time { return now } - - if _, ok := s.Weather(); ok { - t.Fatal("weather before any fetch") - } - if err := s.FetchWeather(context.Background()); err != nil { - t.Fatal(err) - } - w, ok := s.Weather() - if !ok || string(w) != `{"tempC":12,"icon":"sun"}` { - t.Fatalf("weather = %s, %v", w, ok) - } - now = now.Add(2*time.Hour + 59*time.Minute) - if _, ok := s.Weather(); !ok { - t.Fatal("weather expired early") - } - now = now.Add(time.Minute) - if _, ok := s.Weather(); ok { - t.Fatal("weather older than 3 h still served") - } - - // No weather object clears it. - body = `{"weather":null}` - s.FetchWeather(context.Background()) - if _, ok := s.Weather(); ok { - t.Fatal("null weather kept an old value") - } - body = `{"weather":[1,2]}` - s.FetchWeather(context.Background()) - if _, ok := s.Weather(); ok { - t.Fatal("non-object weather accepted") - } -} - -// channelServer serves a channel file at /channel.json and the package at -// /pkg.mbu, counting package downloads. -type channelServer struct { - *httptest.Server - downloads atomic.Int32 - channel Channel - pkg []byte -} - -func newChannelServer(t *testing.T, version string, pkg []byte) *channelServer { - cs := &channelServer{pkg: pkg} - cs.channel = Channel{Version: version, URL: "pkg.mbu", SHA256: hexSHA(pkg), Bytes: int64(len(pkg))} - cs.Server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - switch r.URL.Path { - case "/channel.json": - json.NewEncoder(w).Encode(cs.channel) - case "/pkg.mbu": - cs.downloads.Add(1) - w.Write(cs.pkg) - default: - http.NotFound(w, r) - } - })) - t.Cleanup(cs.Close) - return cs -} - -func setAppVersion(t *testing.T, l store.Layout, v string) { - if _, err := l.State().Update(func(s *state.State) error { s.AppVersion = v; return nil }); err != nil { - t.Fatal(err) - } -} - -func TestAppChannel(t *testing.T) { - cases := []struct { - name string - installed string - channel string - downloads int32 - waiting string - }{ - {"newer waits", "2.0.0", "2.1.0", 1, "2.1.0"}, - {"nothing installed waits (and installs at once)", "", "2.1.0", 1, "2.1.0"}, - {"equal skips", "2.1.0", "2.1.0", 0, ""}, - {"older skips", "2.2.0", "2.1.0", 0, ""}, - } - for _, tc := range cases { - t.Run(tc.name, func(t *testing.T) { - cs := newChannelServer(t, tc.channel, appPackage(t, tc.channel)) - e := newEnv(t, "http://unused") - e.cfg.AppChannelSet = strp(cs.URL + "/channel.json") - setAppVersion(t, e.layout, tc.installed) - if err := e.syncer.CheckChannels(context.Background()); err != nil { - t.Fatal(err) - } - if n := cs.downloads.Load(); n != tc.downloads { - t.Errorf("downloads = %d, want %d", n, tc.downloads) - } - if got := e.updates.Pending(mbu.TypeApp); got != tc.waiting { - t.Errorf("waiting = %q, want %q", got, tc.waiting) - } - st, _ := e.layout.State().Load() - if st.AppVersion != tc.installed { - t.Errorf("app version = %q: the channel check installed it", st.AppVersion) - } - // A second check does not download what is already waiting. - if err := e.syncer.CheckChannels(context.Background()); err != nil { - t.Fatal(err) - } - if n := cs.downloads.Load(); n != tc.downloads { - t.Errorf("downloads after a second check = %d, want %d", n, tc.downloads) - } - }) - } -} - -func TestAppChannelShaMismatch(t *testing.T) { - cs := newChannelServer(t, "2.1.0", appPackage(t, "2.1.0")) - cs.channel.SHA256 = strings.Repeat("0", 64) - e := newEnv(t, "http://unused") - e.cfg.AppChannelSet = strp(cs.URL + "/channel.json") - err := e.syncer.checkChannel(context.Background(), mbu.TypeApp, cs.URL+"/channel.json") - if err == nil || !strings.Contains(err.Error(), "SHA-256") { - t.Fatalf("err = %v", err) - } - if st, _ := e.layout.State().Load(); st.AppVersion != "" { - t.Fatalf("installed %q despite the hash mismatch", st.AppVersion) - } -} - -func TestAppChannelSizeMismatch(t *testing.T) { - cs := newChannelServer(t, "2.1.0", appPackage(t, "2.1.0")) - cs.channel.Bytes -= 10 - e := newEnv(t, "http://unused") - err := e.syncer.checkChannel(context.Background(), mbu.TypeApp, cs.URL+"/channel.json") - if err == nil || !strings.Contains(err.Error(), "larger than") { - t.Fatalf("err = %v", err) - } -} - -func TestChannelValidation(t *testing.T) { - cs := newChannelServer(t, "2.1", appPackage(t, "2.1.0")) - e := newEnv(t, "http://unused") - err := e.syncer.checkChannel(context.Background(), mbu.TypeApp, cs.URL+"/channel.json") - if err == nil || !strings.Contains(err.Error(), "MAJOR.MINOR.PATCH") { - t.Fatalf("err = %v", err) - } -} - -func TestAgentChannel(t *testing.T) { - cases := []struct { - name string - running string - channel string - rejected []string - downloads int32 - waiting string - }{ - {"newer waits", "0.3.0", "0.4.0", nil, 1, "0.4.0"}, - {"equal skips", "0.3.0", "0.3.0", nil, 0, ""}, - {"older skips", "0.3.0", "0.2.9", nil, 0, ""}, - {"rejected skips", "0.3.0", "0.4.0", []string{"0.4.0"}, 0, ""}, - {"dev build skips", "dev", "0.4.0", nil, 0, ""}, - } - for _, tc := range cases { - t.Run(tc.name, func(t *testing.T) { - cs := newChannelServer(t, tc.channel, agentPackage(t, tc.channel)) - e := newEnv(t, "http://unused") - e.cfg.AgentChannelSet = strp(cs.URL + "/channel.json") - e.syncer.d.AgentVersion = tc.running - if tc.rejected != nil { - e.layout.State().Update(func(s *state.State) error { s.AgentVersionsRejected = tc.rejected; return nil }) - } - e.syncer.CheckChannels(context.Background()) - if n := cs.downloads.Load(); n != tc.downloads { - t.Errorf("downloads = %d, want %d", n, tc.downloads) - } - if got := e.updates.Pending(mbu.TypeAgent); got != tc.waiting { - t.Errorf("waiting = %q, want %q", got, tc.waiting) - } - if _, err := os.Stat(e.layout.StagedReady()); err == nil { - t.Error("the channel check staged the agent instead of leaving it waiting") - } - }) - } -} - -func TestAutoUpdateOffSkipsChannels(t *testing.T) { - cs := newChannelServer(t, "2.1.0", appPackage(t, "2.1.0")) - e := newEnv(t, "http://127.0.0.1:1") - e.cfg.AppChannelSet = strp(cs.URL + "/channel.json") - e.cfg.AutoUpdateSet = boolp(false) - e.cfg.ContentSyncSet = boolp(false) - e.syncer.channelFirstDelay = time.Millisecond - ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond) - defer cancel() - e.syncer.Run(ctx) - if cs.downloads.Load() != 0 { - t.Fatal("channel followed with auto_update off") - } - if e.syncer.Status().Enabled { - t.Fatal("status reports sync enabled with content_sync off") - } -} - -// A channel request that gets no answer (a dead pooled connection, a board -// that just lost its network) is given up on and retried once on a new -// connection, instead of waiting minutes for response headers. -func TestChannelFetchRetriesAStuckRequest(t *testing.T) { - cs := newChannelServer(t, "2.1.0", appPackage(t, "2.1.0")) - release := make(chan struct{}) - var calls atomic.Int32 - stuck := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - if calls.Add(1) == 1 { - select { - case <-release: - case <-r.Context().Done(): - } - return - } - http.Redirect(w, r, cs.URL+"/channel.json", http.StatusFound) - })) - defer stuck.Close() - defer close(release) - - e := newEnv(t, "http://127.0.0.1:1") - e.syncer.channelTimeout = 200 * time.Millisecond - ch, err := e.syncer.fetchChannel(context.Background(), stuck.URL+"/channel.json") - if err != nil { - t.Fatal(err) - } - if ch.Version != "2.1.0" || calls.Load() != 2 { - t.Fatalf("version %q after %d calls", ch.Version, calls.Load()) - } -} - -// A server that answers is not asked twice. -func TestChannelFetchDoesNotRetryAnAnswer(t *testing.T) { - var calls atomic.Int32 - srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - calls.Add(1) - http.NotFound(w, r) - })) - defer srv.Close() - e := newEnv(t, "http://127.0.0.1:1") - if _, err := e.syncer.fetchChannel(context.Background(), srv.URL+"/channel.json"); err == nil || calls.Load() != 1 { - t.Fatalf("err %v after %d calls", err, calls.Load()) - } -} - -// A failed check is retried soon, not after the full channel interval. -func TestFailedChannelCheckRetriesSoon(t *testing.T) { - var calls atomic.Int32 - srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - calls.Add(1) - http.Error(w, "down", http.StatusBadGateway) - })) - defer srv.Close() - e := newEnv(t, "http://127.0.0.1:1") - e.cfg.AppChannelSet = strp(srv.URL + "/channel.json") - e.cfg.ContentSyncSet = boolp(false) - e.syncer.channelFirstDelay = time.Millisecond - e.syncer.channelRetry = 10 * time.Millisecond - ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) - defer cancel() - go e.syncer.Run(ctx) - for calls.Load() < 3 { - if ctx.Err() != nil { - t.Fatalf("%d checks in 5s; a failure waited the full interval", calls.Load()) - } - time.Sleep(5 * time.Millisecond) - } - if e.updates.Info().LastCheckError == "" { - t.Fatal("the failure was not reported") - } -} diff --git a/internal/boardsync/download.go b/internal/boardsync/download.go deleted file mode 100644 index 0122868..0000000 --- a/internal/boardsync/download.go +++ /dev/null @@ -1,60 +0,0 @@ -package boardsync - -import ( - "crypto/ed25519" - "errors" - "fmt" - "hash" - "io" - "net/http" - "net/url" - "os" - "time" - - "github.com/LensBridge/agent/internal/devauth" - "github.com/LensBridge/agent/internal/mbu" -) - -// maxPackage is the largest package the board will download. -const maxPackage = mbu.MaxPackageBytes - -var errTooLarge = fmt.Errorf("the download is larger than %d MiB, the most a package may be", maxPackage>>20) - -func signRequest(req *http.Request, body []byte, deviceID string, key ed25519.PrivateKey, now time.Time) { - devauth.Sign(req, body, deviceID, key, now) -} - -func urlQueryEscape(s string) string { return url.QueryEscape(s) } - -// saveCapped streams r into a new file at path, reading at most limit bytes; -// anything longer is errTooLarge and the file is removed. When h is not nil -// every byte is also hashed into it. -func saveCapped(path string, r io.Reader, limit int64, h hash.Hash) (int64, error) { - f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o640) - if err != nil { - return 0, err - } - var w io.Writer = f - if h != nil { - w = io.MultiWriter(f, h) - } - // One byte past the limit tells "exactly at the limit" from "too big". - n, err := io.Copy(w, io.LimitReader(r, limit+1)) - if err == nil && n > limit { - err = errTooLarge - } - if err == nil { - err = f.Sync() - } - if cerr := f.Close(); err == nil { - err = cerr - } - if err != nil { - os.Remove(path) - if errors.Is(err, errTooLarge) { - return n, errTooLarge - } - return n, err - } - return n, nil -} diff --git a/internal/boardsync/refresh.go b/internal/boardsync/refresh.go deleted file mode 100644 index 43e34b5..0000000 --- a/internal/boardsync/refresh.go +++ /dev/null @@ -1,105 +0,0 @@ -package boardsync - -import ( - "context" - "fmt" - "math/rand" - "net/http" - "net/url" - "os" - "strings" - "time" - - "github.com/coder/websocket" -) - -// refreshStable is how long a refresh connection must stay up before the -// reconnect backoff starts over. A server that accepts and immediately drops -// the socket would otherwise be redialled every second. -const refreshStable = 30 * time.Second - -// refreshLoop holds the backend's refresh channel open, the same socket the -// hosted board listens on. The backend sends a message whenever something on -// the board's content changes; each one schedules a content sync. -func (s *Syncer) refreshLoop(ctx context.Context) { - wsURL, err := refreshURL(s.d.Cfg.BackendURL, s.d.Cfg.DeviceID) - if err != nil { - s.log.Warn("no refresh channel: cannot derive its address from backend_url", "err", err) - return - } - backoff := s.refreshMinBackoff - for { - started := time.Now() - err := s.refreshOnce(ctx, wsURL) - if ctx.Err() != nil { - return - } - if time.Since(started) >= refreshStable { - backoff = s.refreshMinBackoff - } - s.log.Debug("refresh channel closed", "err", err, "retryIn", backoff) - if !sleep(ctx, backoff+jitter(backoff)) { - return - } - backoff = min(backoff*2, s.refreshMaxBackoff) - } -} - -func (s *Syncer) refreshOnce(ctx context.Context, wsURL string) error { - dialCtx, cancel := context.WithTimeout(ctx, 15*time.Second) - defer cancel() - // The shared client's overall timeout is for downloads; the socket is - // meant to stay open for hours and is bounded by dialCtx instead. - wsClient := *s.client - wsClient.Timeout = 0 - conn, _, err := websocket.Dial(dialCtx, wsURL, &websocket.DialOptions{ - HTTPClient: &wsClient, - HTTPHeader: http.Header{"User-Agent": []string{"musallahboard-agent/" + s.d.AgentVersion}}, - }) - if err != nil { - return fmt.Errorf("dial: %w", err) - } - defer conn.CloseNow() - conn.SetReadLimit(64 << 10) - s.log.Debug("refresh channel connected") - for { - typ, _, err := conn.Read(ctx) - if err != nil { - return err - } - if typ == websocket.MessageText { - s.Trigger() - } - } -} - -// refreshURL derives ws(s):///api/refresh-musallahboard?deviceId= -// from backend_url. -func refreshURL(backendURL, deviceID string) (string, error) { - u, err := url.Parse(strings.TrimRight(backendURL, "/")) - if err != nil { - return "", err - } - switch u.Scheme { - case "https": - u.Scheme = "wss" - case "http": - u.Scheme = "ws" - default: - return "", fmt.Errorf("backend_url scheme %q is not http or https", u.Scheme) - } - u.Path = strings.TrimRight(u.Path, "/") + "/api/refresh-musallahboard" - u.RawPath = "" - u.RawQuery = url.Values{"deviceId": {deviceID}}.Encode() - u.Fragment = "" - return u.String(), nil -} - -func jitter(b time.Duration) time.Duration { - if b < 4 { - return 0 - } - return time.Duration(rand.Int63n(int64(b / 4))) -} - -func removeAll(p string) { _ = os.RemoveAll(p) } diff --git a/internal/commands/kiosk_restart.go b/internal/commands/kiosk_restart.go deleted file mode 100644 index e4b0605..0000000 --- a/internal/commands/kiosk_restart.go +++ /dev/null @@ -1,26 +0,0 @@ -package commands - -import ( - "context" - "encoding/json" - "fmt" - "os/exec" - "strings" -) - -// KioskRestart bounces the musallahboard-kiosk systemd unit. Requires a -// sudoers rule allowing `/bin/systemctl restart musallahboard-kiosk.service` -// without a password (installed by packaging/sudoers.d/musallahboard-agent). -type KioskRestart struct{} - -func (h *KioskRestart) Kind() string { return "kiosk.restart" } - -func (h *KioskRestart) Execute(ctx context.Context, _ json.RawMessage, progress ProgressFn) (any, error) { - progress("restarting", "systemctl restart musallahboard-kiosk.service", nil) - cmd := exec.CommandContext(ctx, "sudo", "-n", "/bin/systemctl", "restart", "musallahboard-kiosk.service") - out, err := cmd.CombinedOutput() - if err != nil { - return nil, fmt.Errorf("systemctl: %v: %s", err, strings.TrimSpace(string(out))) - } - return map[string]any{"restarted": true}, nil -} diff --git a/internal/config/owner_unix.go b/internal/config/owner_unix.go deleted file mode 100644 index 9648c43..0000000 --- a/internal/config/owner_unix.go +++ /dev/null @@ -1,26 +0,0 @@ -//go:build !windows - -package config - -import ( - "os" - "syscall" -) - -type owner struct{ uid, gid int } - -// fileOwner returns the uid/gid of path, or false if it cannot be read. -func fileOwner(path string) (owner, bool) { - fi, err := os.Stat(path) - if err != nil { - return owner{}, false - } - st, ok := fi.Sys().(*syscall.Stat_t) - if !ok { - return owner{}, false - } - return owner{uid: int(st.Uid), gid: int(st.Gid)}, true -} - -// apply is best-effort: EPERM when not root and already the owner is harmless. -func (o owner) apply(path string) { _ = os.Chown(path, o.uid, o.gid) } diff --git a/internal/config/owner_windows.go b/internal/config/owner_windows.go deleted file mode 100644 index 1b25ed3..0000000 --- a/internal/config/owner_windows.go +++ /dev/null @@ -1,11 +0,0 @@ -//go:build windows - -package config - -// Ownership is a no-op on Windows; the daemon only targets Linux. These stubs -// exist so the package builds for dev tooling on Windows. -type owner struct{} - -func fileOwner(string) (owner, bool) { return owner{}, false } - -func (owner) apply(string) {} diff --git a/internal/clock/clock.go b/internal/core/clock/clock.go similarity index 98% rename from internal/clock/clock.go rename to internal/core/clock/clock.go index a46d8b6..6eefedd 100644 --- a/internal/clock/clock.go +++ b/internal/core/clock/clock.go @@ -40,10 +40,10 @@ import ( "sync" "time" - "github.com/LensBridge/agent/internal/clock/timesync" - "github.com/LensBridge/agent/internal/importer" - "github.com/LensBridge/agent/internal/state" - "github.com/LensBridge/agent/internal/store" + "github.com/LensBridge/agent/internal/core/clock/timesync" + "github.com/LensBridge/agent/internal/core/importer" + "github.com/LensBridge/agent/internal/core/state" + "github.com/LensBridge/agent/internal/core/store" ) const ( diff --git a/internal/clock/clock_test.go b/internal/core/clock/clock_test.go similarity index 99% rename from internal/clock/clock_test.go rename to internal/core/clock/clock_test.go index c0f60d1..d6e113e 100644 --- a/internal/clock/clock_test.go +++ b/internal/core/clock/clock_test.go @@ -7,9 +7,9 @@ import ( "testing" "time" - "github.com/LensBridge/agent/internal/importer" - "github.com/LensBridge/agent/internal/state" - "github.com/LensBridge/agent/internal/store" + "github.com/LensBridge/agent/internal/core/importer" + "github.com/LensBridge/agent/internal/core/state" + "github.com/LensBridge/agent/internal/core/store" ) type fake struct { diff --git a/internal/clock/settime_linux.go b/internal/core/clock/settime_linux.go similarity index 100% rename from internal/clock/settime_linux.go rename to internal/core/clock/settime_linux.go diff --git a/internal/clock/settime_other.go b/internal/core/clock/settime_other.go similarity index 100% rename from internal/clock/settime_other.go rename to internal/core/clock/settime_other.go diff --git a/internal/clock/timesync/timesync.go b/internal/core/clock/timesync/timesync.go similarity index 100% rename from internal/clock/timesync/timesync.go rename to internal/core/clock/timesync/timesync.go diff --git a/internal/config/config.go b/internal/core/config/config.go similarity index 63% rename from internal/config/config.go rename to internal/core/config/config.go index c3a3db7..63af393 100644 --- a/internal/config/config.go +++ b/internal/core/config/config.go @@ -1,37 +1,50 @@ -// Package config persists the agent's runtime identity at /etc/musallahboard/agent.toml. +// Package config is the board's /etc/musallahboard/agent.toml +// (docs/architecture.md, section 11). Every key is optional: a board with no +// agent.toml at all is an unprovisioned board, which still runs, shows its +// "not set up yet" screen and takes USB sticks. // -// Schema: +// Identity, written by a provision package (setup file) or `enroll`: // -// device_id = "uuid" -// backend_url = "https://api.utmmsa.ca" -// websocket_url = "wss://api.utmmsa.ca/api/agent/ws" -// key_path = "/etc/musallahboard/agent.key" +// device_id = "uuid" +// display_name = "North Musallah" +// provision_sequence = 1700000000000 // -// Optional keys (docs/architecture.md, section 11): service_port, usb_import, -// content_sync, content_days, auto_update, app_channel_url, agent_channel_url, -// update_time, insecure_dev. +// The optional online layer, also from the setup file or `enroll`: +// +// backend_url = "https://api.example.org" +// claim_secret = "" until the board has claimed its device key +// websocket_url = "wss://api.example.org/api/agent/ws" from the claim or enroll reply // // backend_url must be https:// and websocket_url wss:// on the same host, -// unless insecure_dev = true (CheckTransport). +// unless insecure_dev = true (CheckTransport). The device key is always at +// KeyPath. // -// Identity is proved by signing a server-issued challenge with the Ed25519 key -// at KeyPath. +// Board options: service_port, usb_import, content_sync, content_days, +// auto_update, app_channel_url, agent_channel_url, update_time, insecure_dev. package config import ( "errors" "fmt" + "io/fs" "net/url" "os" "path/filepath" "strings" + "sync" "time" "github.com/BurntSushi/toml" + + "github.com/LensBridge/agent/internal/core/fsutil" + "github.com/LensBridge/agent/internal/core/mbu" ) -// DefaultKeyPath is where Save writes if the caller leaves Config.KeyPath empty. -const DefaultKeyPath = "/etc/musallahboard/agent.key" +// DefaultPath is agent.toml on a board. +const DefaultPath = "/etc/musallahboard/agent.toml" + +// KeyPath is the device key (package keystore), next to agent.toml. +const KeyPath = "/etc/musallahboard/agent.key" // Channel defaults (section 9.4). %s is the board's GOARCH. const ( @@ -41,17 +54,15 @@ const ( DefaultUpdateHour = 23 ) -// Config is the persisted agent configuration written at enrollment. -// -// The first four fields are required at runtime; Load returns an error if any -// is empty. Everything else is optional: a nil pointer means "not set", and -// the accessor methods supply the default, so a freshly enrolled config needs -// none of them. +// Config is agent.toml. Every field is optional. For the options, a nil +// pointer means "not set" and the accessor methods supply the default. type Config struct { - DeviceID string `toml:"device_id"` - BackendURL string `toml:"backend_url"` - WebSocketURL string `toml:"websocket_url"` - KeyPath string `toml:"key_path"` + DeviceID string `toml:"device_id,omitempty"` + DisplayName string `toml:"display_name,omitempty"` + ProvisionSequence int64 `toml:"provision_sequence,omitempty"` + BackendURL string `toml:"backend_url,omitempty"` + ClaimSecret string `toml:"claim_secret,omitempty"` + WebSocketURL string `toml:"websocket_url,omitempty"` ServicePortSet *bool `toml:"service_port,omitempty"` USBImportSet *bool `toml:"usb_import,omitempty"` @@ -68,6 +79,14 @@ type Config struct { InsecureDevSet *bool `toml:"insecure_dev,omitempty"` } +// Provisioned reports whether the board has an identity (a device id). +func (c *Config) Provisioned() bool { return c.DeviceID != "" } + +// Online reports whether the board is set up for the online layer: it has +// an identity and a backend to talk to. It may still have to claim its +// device key first (no websocket_url yet). +func (c *Config) Online() bool { return c.DeviceID != "" && c.BackendURL != "" } + // InsecureDev reports whether this board may talk to its backend without TLS. // Development boards only. func (c *Config) InsecureDev() bool { return boolOr(c.InsecureDevSet, false) } @@ -93,9 +112,10 @@ func (c *Config) ContentSync() bool { return boolOr(c.ContentSyncSet, true) } // AutoUpdate reports whether the release channels are followed. func (c *Config) AutoUpdate() bool { return boolOr(c.AutoUpdateSet, true) } -// ContentDays is the window of a synced content package, 1-31. +// ContentDays is the window of a synced content package, from 1 to the most +// a content package may cover (mbu.MaxContentDays). func (c *Config) ContentDays() int { - if c.ContentDaysSet == nil || *c.ContentDaysSet < 1 || *c.ContentDaysSet > 31 { + if c.ContentDaysSet == nil || *c.ContentDaysSet < 1 || *c.ContentDaysSet > mbu.MaxContentDays { return DefaultContentDays } return *c.ContentDaysSet @@ -204,7 +224,7 @@ func sameHost(a, b string) bool { // CheckTransport applies CheckBackendURL and CheckWebSocketURL to this // config. The daemon calls it before it builds anything that talks to the -// backend (content sync, the refresh channel, release checks, the command +// backend (content sync, release checks, the command // WebSocket) and talks to none of them when it fails. // // Load does not call it: a board with an insecure config still shows the @@ -216,43 +236,37 @@ func (c *Config) CheckTransport() error { return CheckWebSocketURL(c.WebSocketURL, c.BackendURL, c.InsecureDev()) } +// Load reads the config at path. A missing file is the empty config of an +// unprovisioned board, not an error. func Load(path string) (*Config, error) { var c Config if _, err := toml.DecodeFile(path, &c); err != nil { + if errors.Is(err, fs.ErrNotExist) { + return &Config{}, nil + } return nil, fmt.Errorf("read %s: %w", path, err) } - if c.KeyPath == "" { - c.KeyPath = DefaultKeyPath - } - if c.DeviceID == "" || c.BackendURL == "" || c.WebSocketURL == "" { - return nil, fmt.Errorf("config %s is incomplete (run `agent enroll` first)", path) - } return &c, nil } -// SetServicePort rewrites service_port in the config at path, leaving every -// other field as it was. The file -// keeps its owner: this runs as root via sudo, but the daemon reading the -// result runs as the service user, and Save creates a fresh 0600 file that -// would otherwise belong to root. +// SetServicePort rewrites service_port in the config at path (creating it if +// need be), leaving every other field as it was. func SetServicePort(path string, on bool) error { c, err := Load(path) if err != nil { return err } - owner, haveOwner := fileOwner(path) c.ServicePortSet = &on - if err := Save(path, c); err != nil { - return err - } - if haveOwner { - owner.apply(path) - } - return nil + return Save(path, c) } // Save writes the config atomically: tmp file + fsync + rename. Survives a // power cut mid-write — either the old file is intact or the new one is. +// +// The file gets the owner of its directory. Root tools (`enroll`, +// `service-port`) write it under sudo, but the daemon that reads it runs as +// the service user, which owns /etc/musallahboard; run as that user, this is +// a no-op. func Save(path string, c *Config) error { if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { return fmt.Errorf("mkdir: %w", err) @@ -277,9 +291,75 @@ func Save(path string, c *Config) error { os.Remove(tmp) return fmt.Errorf("close: %w", err) } + fsutil.ChownToDirOwner(tmp, filepath.Dir(path)) if err := os.Rename(tmp, path); err != nil { os.Remove(tmp) return fmt.Errorf("rename: %w", err) } return nil } + +// Live is agent.toml as the daemon holds it: read once at start, changed by +// the importer when it applies a setup file (and by the online layer when a +// claim completes), and read again by everything that needs the board's +// identity. Each change is saved before anyone sees it. +type Live struct { + path string + + mu sync.Mutex + cur Config + changed chan struct{} +} + +// Open reads the config at path into a Live. On an error it still returns a +// Live, holding the empty config, so the board runs as unprovisioned while +// the caller reports why. +func Open(path string) (*Live, error) { + l := &Live{path: path, changed: make(chan struct{})} + c, err := Load(path) + if err != nil { + return l, err + } + l.cur = *c + return l, nil +} + +// InMemory is a Live that holds c and never saves it, for tests and tools. +func InMemory(c Config) *Live { + return &Live{cur: c, changed: make(chan struct{})} +} + +// Get returns a copy of the current config. +func (l *Live) Get() *Config { + l.mu.Lock() + defer l.mu.Unlock() + c := l.cur + return &c +} + +// Update applies fn to a copy of the current config and saves it; only then +// does it become current. fn's error aborts without saving. +func (l *Live) Update(fn func(*Config) error) error { + l.mu.Lock() + defer l.mu.Unlock() + next := l.cur + if err := fn(&next); err != nil { + return err + } + if l.path != "" { + if err := Save(l.path, &next); err != nil { + return err + } + } + l.cur = next + close(l.changed) + l.changed = make(chan struct{}) + return nil +} + +// Changed returns a channel closed at the next Update. +func (l *Live) Changed() <-chan struct{} { + l.mu.Lock() + defer l.mu.Unlock() + return l.changed +} diff --git a/internal/config/config_test.go b/internal/core/config/config_test.go similarity index 74% rename from internal/config/config_test.go rename to internal/core/config/config_test.go index 292ee6b..7dff88d 100644 --- a/internal/config/config_test.go +++ b/internal/core/config/config_test.go @@ -8,6 +8,8 @@ import ( "testing" ) +// baseTOML keeps key_path, which configs written before it was dropped +// carry: an unknown key must not stop a board from loading its config. const baseTOML = `device_id = "3f2a1b4c-0000-4000-8000-000000000001" backend_url = "https://api.example.com" websocket_url = "wss://api.example.com/api/agent/ws" @@ -46,6 +48,9 @@ func TestDefaults(t *testing.T) { if !strings.HasSuffix(c.AgentChannelURL("arm64"), "agent-channel-arm64.json") { t.Errorf("agent channel = %s", c.AgentChannelURL("arm64")) } + if c, _ := Load(writeConfig(t, baseTOML+"content_days = 92\n")); c.ContentDays() != 92 { + t.Errorf("content_days = 92 gave %d", c.ContentDays()) + } c, _ = Load(writeConfig(t, baseTOML+"app_channel_url = \"\"\ncontent_days = 99\n")) if c.AppChannelURL() != "" || c.ContentDays() != DefaultContentDays { t.Errorf("overrides wrong: app=%q days=%d", c.AppChannelURL(), c.ContentDays()) @@ -64,8 +69,54 @@ func TestSetServicePortKeepsOtherFields(t *testing.T) { if c.ServicePort() || c.DeviceID != "3f2a1b4c-0000-4000-8000-000000000001" { t.Errorf("after SetServicePort(false): %+v", c) } - if err := SetServicePort(filepath.Join(t.TempDir(), "missing.toml"), true); err == nil { - t.Fatal("expected an error for a missing config") + // An unprovisioned board has no config yet; the switch creates one. + missing := filepath.Join(t.TempDir(), "missing.toml") + if err := SetServicePort(missing, true); err != nil { + t.Fatal(err) + } + if c, err := Load(missing); err != nil || !c.ServicePort() || c.Provisioned() { + t.Fatalf("created config: %+v, %v", c, err) + } +} + +// No agent.toml is an unprovisioned board, which still runs. +func TestLoadMissingIsUnprovisioned(t *testing.T) { + c, err := Load(filepath.Join(t.TempDir(), "agent.toml")) + if err != nil { + t.Fatal(err) + } + if c.Provisioned() || c.Online() || !c.USBImport() { + t.Fatalf("missing config: %+v", c) + } + if _, err := Load(writeConfig(t, "device_id = [")); err == nil { + t.Fatal("a corrupt config loaded") + } +} + +func TestLiveUpdateSavesAndNotifies(t *testing.T) { + p := filepath.Join(t.TempDir(), "agent.toml") + l, err := Open(p) + if err != nil { + t.Fatal(err) + } + changed := l.Changed() + if err := l.Update(func(c *Config) error { c.DeviceID = "d"; return nil }); err != nil { + t.Fatal(err) + } + select { + case <-changed: + default: + t.Fatal("Update did not signal a change") + } + if l.Get().DeviceID != "d" { + t.Fatal("Update not current") + } + if c, _ := Load(p); c.DeviceID != "d" { + t.Fatal("Update not saved") + } + // A failed update changes nothing. + if err := l.Update(func(c *Config) error { c.DeviceID = "e"; return errors.New("no") }); err == nil || l.Get().DeviceID != "d" { + t.Fatalf("failed update applied: %v %q", err, l.Get().DeviceID) } } @@ -133,7 +184,7 @@ func TestLoadKeepsInsecureConfigReadable(t *testing.T) { // The opt-in is written as an explicit key, and only when on. func TestSaveWritesInsecureDevOnlyWhenSet(t *testing.T) { p := filepath.Join(t.TempDir(), "agent.toml") - c := &Config{DeviceID: "d", BackendURL: "https://a", WebSocketURL: "wss://a/ws", KeyPath: "/k"} + c := &Config{DeviceID: "d", BackendURL: "https://a", WebSocketURL: "wss://a/ws"} if err := Save(p, c); err != nil { t.Fatal(err) } diff --git a/internal/events/events.go b/internal/core/events/events.go similarity index 98% rename from internal/events/events.go rename to internal/core/events/events.go index 4bfbfeb..10eb995 100644 --- a/internal/events/events.go +++ b/internal/core/events/events.go @@ -14,7 +14,7 @@ import ( "sync" "time" - "github.com/LensBridge/agent/internal/notice" + "github.com/LensBridge/agent/internal/core/notice" ) // Event is one SSE message. diff --git a/internal/fsutil/fs_unix.go b/internal/core/fsutil/fs_unix.go similarity index 70% rename from internal/fsutil/fs_unix.go rename to internal/core/fsutil/fs_unix.go index 7a0d227..f5cae02 100644 --- a/internal/fsutil/fs_unix.go +++ b/internal/core/fsutil/fs_unix.go @@ -43,3 +43,17 @@ func LockDir(dir string) (unlock func(), err error) { f.Close() }, nil } + +// ChownToDirOwner gives path the owner and group of dir. Root tools (the USB +// helper, `enroll`, `service-port`) write files the unprivileged daemon must +// read, into directories the daemon owns. Best effort: not root, it fails +// harmlessly, and then the caller owns the file already. +func ChownToDirOwner(path, dir string) { + fi, err := os.Stat(dir) + if err != nil { + return + } + if st, ok := fi.Sys().(*syscall.Stat_t); ok { + _ = os.Chown(path, int(st.Uid), int(st.Gid)) + } +} diff --git a/internal/fsutil/fs_windows.go b/internal/core/fsutil/fs_windows.go similarity index 88% rename from internal/fsutil/fs_windows.go rename to internal/core/fsutil/fs_windows.go index 2a2de94..88ad1ae 100644 --- a/internal/fsutil/fs_windows.go +++ b/internal/core/fsutil/fs_windows.go @@ -9,3 +9,5 @@ package fsutil func SyncDir(string) error { return nil } func LockDir(string) (func(), error) { return func() {}, nil } + +func ChownToDirOwner(string, string) {} diff --git a/internal/fsutil/fsutil.go b/internal/core/fsutil/fsutil.go similarity index 100% rename from internal/fsutil/fsutil.go rename to internal/core/fsutil/fsutil.go diff --git a/internal/importer/importer.go b/internal/core/importer/importer.go similarity index 86% rename from internal/importer/importer.go rename to internal/core/importer/importer.go index 1b7cb1c..7fc50bb 100644 --- a/internal/importer/importer.go +++ b/internal/core/importer/importer.go @@ -21,13 +21,14 @@ import ( "sync" "time" - "github.com/LensBridge/agent/internal/clock/timesync" - "github.com/LensBridge/agent/internal/fsutil" - "github.com/LensBridge/agent/internal/mbu" - "github.com/LensBridge/agent/internal/notice" - "github.com/LensBridge/agent/internal/state" - "github.com/LensBridge/agent/internal/store" - "github.com/LensBridge/agent/internal/trust" + "github.com/LensBridge/agent/internal/core/clock/timesync" + "github.com/LensBridge/agent/internal/core/config" + "github.com/LensBridge/agent/internal/core/fsutil" + "github.com/LensBridge/agent/internal/core/mbu" + "github.com/LensBridge/agent/internal/core/notice" + "github.com/LensBridge/agent/internal/core/state" + "github.com/LensBridge/agent/internal/core/store" + "github.com/LensBridge/agent/internal/core/trust" ) // LocalAPIVersion is the local kiosk API this agent serves (section 7). An app @@ -98,7 +99,7 @@ func (b Batch) OK() bool { return true } -// Screen is the kiosk's update screen (package updatescreen). +// Screen is the kiosk's update screen (kiosk.Screen). type Screen interface { // Active reports whether the screen is up, possibly held over from // before an agent restart for this batch to finish. @@ -109,7 +110,7 @@ type Screen interface { // countdown. Finish(ctx context.Context, n notice.Notice) // Restarting says the agent is about to be replaced. The new agent - // finishes the screen (package agentupdate). + // finishes the screen (selfupdate.Reporter). Restarting(ctx context.Context) } @@ -123,8 +124,10 @@ type Events interface { // Deps is what an Importer needs. type Deps struct { - Layout store.Layout - DeviceID string + Layout store.Layout + // Config is agent.toml. Content binds to its device id, read for every + // package. + Config *config.Live AgentVersion string // Ring loads the trust ring. Called per batch, so `trust fetch` or // `trust add` take effect without a restart. @@ -154,7 +157,7 @@ type Importer struct { } // AgentNotReplaced says the staged agent update ended without replacing this -// agent, so the inbox should carry on (package agentupdate). +// agent, so the inbox should carry on (selfupdate.Reporter). func (im *Importer) AgentNotReplaced() { im.stagedMu.Lock() defer im.stagedMu.Unlock() @@ -177,6 +180,8 @@ func (im *Importer) awaitReplacement() <-chan struct{} { return im.staged } +func (im *Importer) deviceID() string { return im.d.Config.Get().DeviceID } + // New returns an Importer. func New(d Deps) *Importer { if d.Now == nil { @@ -188,6 +193,9 @@ func New(d Deps) *Importer { if d.TrustedNow == nil { d.TrustedNow = timesync.Now } + if d.Config == nil { + d.Config = config.InMemory(config.Config{}) + } return &Importer{d: d} } @@ -215,14 +223,18 @@ type item struct { peek *mbu.Manifest // unverified; ordering and screen only } +// rank orders a batch: a setup file first (it decides which board this is, +// and so which content is for it), then the agent, the app and content. func rank(t mbu.Type) int { switch t { - case mbu.TypeAgent: + case mbu.TypeProvision: return 0 - case mbu.TypeApp: + case mbu.TypeAgent: return 1 + case mbu.TypeApp: + return 2 } - return 2 + return 3 } // progressLine says where a batch someone brought came from. @@ -265,6 +277,7 @@ func (im *Importer) run(ctx context.Context, src Source, files []string) Batch { im.d.Screen.Caption(ctx, caption) } + ambiguous := im.ambiguousSetup(items) ring, ringErr := im.d.Ring() for _, it := range items { name := filepath.Base(it.path) @@ -272,8 +285,14 @@ func (im *Importer) run(ctx context.Context, src Source, files []string) Batch { b.Results = append(b.Results, im.requeue(it.path, name)) continue } - if it.peek != nil && it.peek.Type == mbu.TypeContent && it.peek.DeviceID != "" && it.peek.DeviceID != im.d.DeviceID { - b.Results = append(b.Results, skippedForeign(name)) + if ambiguous && peekType(it) == mbu.TypeProvision { + b.Results = append(b.Results, Result{File: name, Type: mbu.TypeProvision, Action: ActionRejected, + Message: "This USB stick sets up more than one board: use a stick with only this board's setup file", + Detail: "setup files for several devices in one batch on an unprovisioned board"}) + continue + } + if foreign(it.peek, im.deviceID()) { + b.Results = append(b.Results, skippedForeign(name, it.peek.Type)) continue } var r Result @@ -345,8 +364,38 @@ func Summarize(b Batch) notice.Notice { return notice.New(notice.Neutral, "No updates found") } -func skippedForeign(name string) Result { - return Result{File: name, Type: mbu.TypeContent, Action: ActionSkipped, Message: "Content for another board"} +func skippedForeign(name string, t mbu.Type) Result { + msg := "Content for another board" + if t == mbu.TypeProvision { + msg = "Setup file for another board" + } + return Result{File: name, Type: t, Action: ActionSkipped, Message: msg} +} + +// foreign reports whether a package's (unverified) manifest says it is bound +// to another board. Skipping on it is safe: a lie only makes the board ignore +// a package. A setup file is foreign only to a board that has an identity. +func foreign(m *mbu.Manifest, deviceID string) bool { + if m == nil || m.DeviceID == "" || m.DeviceID == deviceID { + return false + } + return m.Type == mbu.TypeContent || (m.Type == mbu.TypeProvision && deviceID != "") +} + +// ambiguousSetup reports whether an unprovisioned board was handed setup +// files for more than one device at once (a USB kit for several boards). It +// takes none of them rather than whichever comes first. +func (im *Importer) ambiguousSetup(items []item) bool { + if im.deviceID() != "" { + return false + } + ids := map[string]bool{} + for _, it := range items { + if it.peek != nil && it.peek.Type == mbu.TypeProvision { + ids[it.peek.DeviceID] = true + } + } + return len(ids) > 1 } func peekType(it item) mbu.Type { @@ -389,9 +438,12 @@ func (im *Importer) one(ctx context.Context, src Source, path, name string, ring now := im.d.Now() switch m.Type { + case mbu.TypeProvision: + return im.provision(pkg, res, show) + case mbu.TypeContent: - if m.DeviceID != im.d.DeviceID { - return skippedForeign(name) + if m.DeviceID != im.deviceID() { + return skippedForeign(name, m.Type) } switch { case m.Sequence < st.ContentSequence: @@ -497,6 +549,8 @@ func describe(m *mbu.Manifest) string { return "board app " + m.Version case mbu.TypeAgent: return "agent " + m.Version + case mbu.TypeProvision: + return "this board's settings" } return "update" } diff --git a/internal/importer/importer_test.go b/internal/core/importer/importer_test.go similarity index 98% rename from internal/importer/importer_test.go rename to internal/core/importer/importer_test.go index 860aff4..6745c03 100644 --- a/internal/importer/importer_test.go +++ b/internal/core/importer/importer_test.go @@ -15,10 +15,11 @@ import ( "testing" "time" - "github.com/LensBridge/agent/internal/mbu" - "github.com/LensBridge/agent/internal/notice" - "github.com/LensBridge/agent/internal/store" - "github.com/LensBridge/agent/internal/trust" + "github.com/LensBridge/agent/internal/core/config" + "github.com/LensBridge/agent/internal/core/mbu" + "github.com/LensBridge/agent/internal/core/notice" + "github.com/LensBridge/agent/internal/core/store" + "github.com/LensBridge/agent/internal/core/trust" ) const dev = "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b" @@ -67,7 +68,7 @@ func setup(t *testing.T) (*Importer, store.Layout, *fakeEvents, *fakeScreen) { ring := trust.NewRing([]ed25519.PublicKey{contentKey.Public().(ed25519.PublicKey)}, []ed25519.PublicKey{releaseKey.Public().(ed25519.PublicKey)}) im := New(Deps{ - Layout: l, DeviceID: dev, AgentVersion: "0.2.0", + Layout: l, Config: config.InMemory(config.Config{DeviceID: dev}), AgentVersion: "0.2.0", Ring: func() (*trust.Ring, error) { return ring, nil }, Screen: sc, Events: ev, Now: func() time.Time { return time.Date(2026, 9, 24, 12, 0, 0, 0, time.UTC) }, diff --git a/internal/importer/inbox.go b/internal/core/importer/inbox.go similarity index 97% rename from internal/importer/inbox.go rename to internal/core/importer/inbox.go index 749de1f..f72c1c2 100644 --- a/internal/importer/inbox.go +++ b/internal/core/importer/inbox.go @@ -9,8 +9,8 @@ import ( "strings" "time" - "github.com/LensBridge/agent/internal/fsutil" - "github.com/LensBridge/agent/internal/notice" + "github.com/LensBridge/agent/internal/core/fsutil" + "github.com/LensBridge/agent/internal/core/notice" ) // InboxPoll is how often the inbox is scanned. Polling rather than inotify: diff --git a/internal/core/importer/provision.go b/internal/core/importer/provision.go new file mode 100644 index 0000000..0f95f62 --- /dev/null +++ b/internal/core/importer/provision.go @@ -0,0 +1,104 @@ +package importer + +import ( + "errors" + + "github.com/LensBridge/agent/internal/core/config" + "github.com/LensBridge/agent/internal/core/mbu" +) + +// provision applies a verified setup file (docs/architecture.md, section 8): +// +// - a board with no identity takes the file's device id and name; +// - a board with an identity takes only a file for its own device id with a +// strictly newer sequence, which updates its name and, when the file has +// one, its backend and claim secret; +// - a file for another device is skipped (another board's, on a USB kit). +// Giving a board another identity means reflashing it. +// +// A file without a backend never removes one: it says nothing about the +// online layer. Everything is written to agent.toml in one atomic save. +// +// The daemon applies it itself, without a root step: agent.toml is the +// daemon's own file (it is the service user's, in the service user's +// directory), so a root-owned copy of this logic would guard nothing the +// daemon could not already change. What a setup file can do is bounded by +// what is in it: an identity and a backend address, never a key, software or +// anything that runs. +func (im *Importer) provision(pkg *mbu.Package, res Result, show func(mbu.Type, string)) Result { + m := pkg.Manifest + raw, err := pkg.ReadFile(mbu.ProvisionFile, mbu.MaxProvisionBytes) + if err != nil { + return failed(res, "A file is damaged or is not a MusallahBoard update", err) + } + p, err := mbu.ParseProvision(raw, m) + if err != nil { + return failed(res, "This setup file cannot be used", err) + } + if r, done := provisionDecision(im.d.Config.Get(), m, res); done { + return r + } + + show(m.Type, "Setting up this board") + first := false + err = im.d.Config.Update(func(c *config.Config) error { + // Decided again under the config's lock: two setup files racing + // (USB and an upload) cannot both win. + if _, done := provisionDecision(c, m, res); done { + return errSuperseded + } + first = !c.Provisioned() + c.DeviceID, c.DisplayName, c.ProvisionSequence = m.DeviceID, p.DisplayName, m.Sequence + if p.BackendURL != "" { + if c.BackendURL != p.BackendURL { + // A new backend: the board claims its key there. + c.WebSocketURL = "" + } + c.BackendURL = p.BackendURL + c.ClaimSecret = "" + if c.WebSocketURL == "" { + c.ClaimSecret = p.ClaimSecret + } + } + return nil + }) + if errors.Is(err, errSuperseded) { + r, _ := provisionDecision(im.d.Config.Get(), m, res) + return r + } + if err != nil { + return failed(res, "Saving this board's settings failed", err) + } + im.d.Logger.Info("setup file applied", "deviceId", m.DeviceID, "displayName", p.DisplayName, + "sequence", m.Sequence, "backendUrl", p.BackendURL, "first", first) + res.Action = ActionInstalled + switch { + case first && p.DisplayName != "": + res.Message = "Set up as " + p.DisplayName + case first: + res.Message = "This board is set up" + default: + res.Message = "Board settings updated" + } + return res +} + +var errSuperseded = errors.New("superseded") + +// provisionDecision is whether a setup file with manifest m may be applied +// to a board with config c; if not, the result to report and true. +func provisionDecision(c *config.Config, m *mbu.Manifest, res Result) (Result, bool) { + switch { + case !c.Provisioned(): + return res, false + case c.DeviceID != m.DeviceID: + return skippedForeign(res.File, m.Type), true + case m.Sequence < c.ProvisionSequence: + res.Action, res.Message = ActionOutdated, "The board already has newer settings" + return res, true + case m.Sequence == c.ProvisionSequence: + res.Action, res.Message = ActionUnchanged, "This setup file is already applied" + return res, true + } + return res, false +} diff --git a/internal/core/importer/provision_test.go b/internal/core/importer/provision_test.go new file mode 100644 index 0000000..419c7be --- /dev/null +++ b/internal/core/importer/provision_test.go @@ -0,0 +1,295 @@ +package importer + +import ( + "archive/zip" + "bytes" + "context" + "crypto/ed25519" + "encoding/base64" + "encoding/json" + "io" + "os" + "path/filepath" + "testing" + "time" + + "github.com/LensBridge/agent/internal/core/config" + "github.com/LensBridge/agent/internal/core/mbu" + "github.com/LensBridge/agent/internal/core/store" + "github.com/LensBridge/agent/internal/core/trust" +) + +const otherDev = "00000000-0000-0000-0000-0000000000aa" + +var secret = base64.RawURLEncoding.EncodeToString(bytes.Repeat([]byte{1}, 32)) + +// setupFile builds a provision package for device at sequence seq, signed +// by k. backend "" makes an offline-only one. +func setupFile(t *testing.T, device string, seq int64, name, backend string, k ed25519.PrivateKey) string { + t.Helper() + p := mbu.Provision{Format: 1, DeviceID: device, DisplayName: name, Sequence: seq, IssuedAt: "2026-11-19T12:00:00Z"} + if backend != "" { + p.BackendURL, p.ClaimSecret = backend, secret + } + raw, _ := json.Marshal(p) + return build(t, mbu.Manifest{Type: mbu.TypeProvision, DeviceID: device, Sequence: seq, CreatedAt: "2026-11-19T12:00:00Z"}, + []mbu.Source{{Path: mbu.ProvisionFile, Data: raw}}, k) +} + +// newImporter is an importer over a temp store whose agent.toml starts as +// cfg, saved at a real path so the test sees what is written. +func newImporter(t *testing.T, cfg config.Config) (*Importer, *config.Live, store.Layout, string) { + t.Helper() + l := store.Layout{Root: t.TempDir()} + path := filepath.Join(t.TempDir(), "agent.toml") + if cfg != (config.Config{}) { + if err := config.Save(path, &cfg); err != nil { + t.Fatal(err) + } + } + live, err := config.Open(path) + if err != nil { + t.Fatal(err) + } + ring := trust.NewRing([]ed25519.PublicKey{contentKey.Public().(ed25519.PublicKey)}, + []ed25519.PublicKey{releaseKey.Public().(ed25519.PublicKey)}) + im := New(Deps{ + Layout: l, Config: live, AgentVersion: "0.2.0", + Ring: func() (*trust.Ring, error) { return ring, nil }, + Now: func() time.Time { return time.Date(2026, 11, 19, 12, 0, 0, 0, time.UTC) }, + TrustedNow: func() (time.Time, bool) { return time.Time{}, false }, + }) + return im, live, l, path +} + +func TestProvisionMatrix(t *testing.T) { + provisioned := config.Config{DeviceID: dev, DisplayName: "Old name", ProvisionSequence: 100} + unsigned := func(t *testing.T) string { + // A valid package with its signature file emptied of signatures. + p := setupFile(t, dev, 200, "N", "", contentKey) + return withoutSignatures(t, p) + } + cases := []struct { + name string + cfg config.Config + file func(t *testing.T) string + action string + wantDev string + wantSeq int64 + }{ + {"unprovisioned takes any device", config.Config{}, + func(t *testing.T) string { return setupFile(t, otherDev, 5, "North", "", contentKey) }, + ActionInstalled, otherDev, 5}, + {"unprovisioned takes an older sequence too", config.Config{}, + func(t *testing.T) string { return setupFile(t, dev, 1, "North", "", contentKey) }, + ActionInstalled, dev, 1}, + {"own device, newer", provisioned, + func(t *testing.T) string { return setupFile(t, dev, 101, "New name", "", contentKey) }, + ActionInstalled, dev, 101}, + {"own device, same", provisioned, + func(t *testing.T) string { return setupFile(t, dev, 100, "New name", "", contentKey) }, + ActionUnchanged, dev, 100}, + {"own device, older", provisioned, + func(t *testing.T) string { return setupFile(t, dev, 99, "New name", "", contentKey) }, + ActionOutdated, dev, 100}, + {"other device", provisioned, + func(t *testing.T) string { return setupFile(t, otherDev, 999, "Theirs", "", contentKey) }, + ActionSkipped, dev, 100}, + {"wrong key (release key)", config.Config{}, + func(t *testing.T) string { return setupFile(t, dev, 5, "N", "", releaseKey) }, + ActionRejected, "", 0}, + {"wrong key, provisioned", provisioned, + func(t *testing.T) string { return setupFile(t, dev, 101, "N", "", releaseKey) }, + ActionRejected, dev, 100}, + {"unsigned", config.Config{}, unsigned, ActionRejected, "", 0}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + im, live, _, path := newImporter(t, tc.cfg) + r := one(t, im.Import(context.Background(), SourceUSB, []string{tc.file(t)})) + if r.Action != tc.action { + t.Fatalf("action = %s (%s: %s), want %s", r.Action, r.Message, r.Detail, tc.action) + } + got := live.Get() + if got.DeviceID != tc.wantDev || got.ProvisionSequence != tc.wantSeq { + t.Fatalf("config = %s seq %d, want %s seq %d", got.DeviceID, got.ProvisionSequence, tc.wantDev, tc.wantSeq) + } + if saved, _ := config.Load(path); saved.DeviceID != tc.wantDev { + t.Fatalf("saved device id = %q, want %q", saved.DeviceID, tc.wantDev) + } + }) + } +} + +// withoutSignatures copies the package at path without its mbu.sig. +func withoutSignatures(t *testing.T, path string) string { + t.Helper() + zr, err := zip.OpenReader(path) + if err != nil { + t.Fatal(err) + } + defer zr.Close() + out := filepath.Join(t.TempDir(), "unsigned.mbu") + f, _ := os.Create(out) + zw := zip.NewWriter(f) + for _, e := range zr.File { + if e.Name == mbu.SignatureName { + continue + } + w, _ := zw.Create(e.Name) + rc, _ := e.Open() + io.Copy(w, rc) + rc.Close() + } + zw.Close() + f.Close() + return out +} + +// The setup stick for an unprovisioned board: its setup file goes first, so +// its content (and only its content) installs in the same batch. +func TestUnprovisionedBoardTakesSetupThenContent(t *testing.T) { + im, live, l, _ := newImporter(t, config.Config{}) + poster := "/" + imgPath() + b := im.Import(context.Background(), SourceUSB, []string{ + content(t, 300, dev, poster, false), + content(t, 301, otherDev, poster, false), + setupFile(t, dev, 5, "North Musallah", "", contentKey), + }) + byType := map[string]string{} + for _, r := range b.Results { + byType[string(r.Type)+" "+r.Action] = r.Message + } + if _, ok := byType["provision installed"]; !ok { + t.Fatalf("results = %+v", b.Results) + } + if _, ok := byType["content installed"]; !ok { + t.Fatalf("own content not installed: %+v", b.Results) + } + if _, ok := byType["content skipped"]; !ok { + t.Fatalf("other board's content not skipped: %+v", b.Results) + } + if c := live.Get(); c.DeviceID != dev || c.DisplayName != "North Musallah" { + t.Fatalf("config = %+v", c) + } + if c, err := l.CurrentContent(); err != nil || c.Manifest.Sequence != 300 { + t.Fatalf("current content = %+v, %v", c, err) + } + if b.Notice.Lines[0] != "Set up as North Musallah" { + t.Fatalf("notice = %+v", b.Notice) + } +} + +// A USB kit for several boards set up nothing on an unprovisioned board: +// which of them it is cannot be guessed. +func TestUnprovisionedBoardRefusesSeveralSetupFiles(t *testing.T) { + im, live, _, _ := newImporter(t, config.Config{}) + b := im.Import(context.Background(), SourceUSB, []string{ + setupFile(t, dev, 5, "A", "", contentKey), + setupFile(t, otherDev, 5, "B", "", contentKey), + }) + for _, r := range b.Results { + if r.Action != ActionRejected { + t.Fatalf("results = %+v", b.Results) + } + } + if live.Get().Provisioned() { + t.Fatal("provisioned from an ambiguous stick") + } +} + +// A provisioned board on a USB kit takes its own setup file and skips the +// others'. +func TestProvisionedBoardOnAKit(t *testing.T) { + im, live, _, _ := newImporter(t, config.Config{DeviceID: dev, ProvisionSequence: 1}) + b := im.Import(context.Background(), SourceUSB, []string{ + setupFile(t, dev, 5, "Mine", "", contentKey), + setupFile(t, otherDev, 5, "Theirs", "", contentKey), + }) + if !b.OK() || live.Get().DisplayName != "Mine" { + t.Fatalf("results = %+v, config %+v", b.Results, live.Get()) + } +} + +func TestProvisionOnlineSettings(t *testing.T) { + const be = "https://api.example.org" + // First setup file with a backend: the board must claim. + im, live, _, _ := newImporter(t, config.Config{}) + one(t, im.Import(context.Background(), SourceUSB, []string{setupFile(t, dev, 5, "N", be+"/", contentKey)})) + c := live.Get() + if c.BackendURL != be || c.ClaimSecret != secret || c.WebSocketURL != "" || !c.Online() { + t.Fatalf("config = %+v", c) + } + + // An enrolled board, same backend: its socket and key stay, no secret. + im, live, _, _ = newImporter(t, config.Config{DeviceID: dev, BackendURL: be, WebSocketURL: "wss://api.example.org/api/agent/ws"}) + one(t, im.Import(context.Background(), SourceUSB, []string{setupFile(t, dev, 5, "N", be, contentKey)})) + if c := live.Get(); c.WebSocketURL == "" || c.ClaimSecret != "" || c.DisplayName != "N" { + t.Fatalf("config = %+v", c) + } + + // A new backend: claim there. + one(t, im.Import(context.Background(), SourceUSB, []string{setupFile(t, dev, 6, "N", "https://other.example.org", contentKey)})) + if c := live.Get(); c.WebSocketURL != "" || c.ClaimSecret != secret || c.BackendURL != "https://other.example.org" { + t.Fatalf("config = %+v", c) + } + + // An offline setup file never takes the backend away. + one(t, im.Import(context.Background(), SourceUSB, []string{setupFile(t, dev, 7, "Renamed", "", contentKey)})) + if c := live.Get(); c.BackendURL != "https://other.example.org" || c.DisplayName != "Renamed" { + t.Fatalf("config = %+v", c) + } +} + +// provision.json must agree with the signed manifest it travels under. +func TestProvisionFileMustMatchManifest(t *testing.T) { + im, live, _, _ := newImporter(t, config.Config{}) + raw, _ := json.Marshal(mbu.Provision{Format: 1, DeviceID: otherDev, Sequence: 5}) + p := build(t, mbu.Manifest{Type: mbu.TypeProvision, DeviceID: dev, Sequence: 5}, + []mbu.Source{{Path: mbu.ProvisionFile, Data: raw}}, contentKey) + if r := one(t, im.Import(context.Background(), SourceUSB, []string{p})); r.Action != ActionRejected { + t.Fatalf("result = %+v", r) + } + if live.Get().Provisioned() { + t.Fatal("provisioned") + } +} + +// A setup file made by the backend (LensBridgeBackend's packager, its test +// content key: seed bytes 0x01..0x20) goes through the real verification and +// provisioning path. If this fails, the two sides disagree on the format. +func TestBackendSampleSetupFile(t *testing.T) { + pub, _ := base64.StdEncoding.DecodeString("ebVWLo/mVPlAeLES6KmLp5AfhTrmlb7X4OORC60ElmQ=") + if trust.KeyID(pub) != "65b60673d6ed884b" { + t.Fatalf("key id = %s", trust.KeyID(pub)) + } + path := filepath.Join(t.TempDir(), "agent.toml") + live, _ := config.Open(path) + ring := trust.NewRing([]ed25519.PublicKey{pub}, nil) + im := New(Deps{Layout: store.Layout{Root: t.TempDir()}, Config: live, + Ring: func() (*trust.Ring, error) { return ring, nil }, + TrustedNow: func() (time.Time, bool) { return time.Time{}, false }}) + r := one(t, im.Import(context.Background(), SourceUSB, []string{"testdata/sample-provision.mbu"})) + if r.Action != ActionInstalled || r.Message != "Set up as North Musallah" { + t.Fatalf("result = %+v", r) + } + c, err := config.Load(path) + if err != nil { + t.Fatal(err) + } + want := config.Config{DeviceID: "00000000-0000-0000-0000-000000000001", DisplayName: "North Musallah", + ProvisionSequence: 1795089600250, BackendURL: "https://api.example.org", + ClaimSecret: "AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE"} + if *c != want { + t.Fatalf("agent.toml = %+v\nwant %+v", *c, want) + } + + // The same file signed by a key the board does not trust is refused. + other := New(Deps{Layout: store.Layout{Root: t.TempDir()}, Config: config.InMemory(config.Config{}), + Ring: func() (*trust.Ring, error) { + return trust.NewRing([]ed25519.PublicKey{contentKey.Public().(ed25519.PublicKey)}, nil), nil + }}) + if r := one(t, other.Import(context.Background(), SourceUSB, []string{"testdata/sample-provision.mbu"})); r.Action != ActionRejected { + t.Fatalf("untrusted key: %+v", r) + } +} diff --git a/internal/core/importer/testdata/sample-provision.mbu b/internal/core/importer/testdata/sample-provision.mbu new file mode 100644 index 0000000..8bc240c Binary files /dev/null and b/internal/core/importer/testdata/sample-provision.mbu differ diff --git a/internal/core/imports_test.go b/internal/core/imports_test.go new file mode 100644 index 0000000..f68dc94 --- /dev/null +++ b/internal/core/imports_test.go @@ -0,0 +1,34 @@ +// Package core_test holds the one rule that keeps the board offline-first: +// nothing under internal/core imports anything under internal/online. The +// online layer may use the core; the core never needs the online layer, so a +// board without it loses no board function. +package core_test + +import ( + "os/exec" + "strings" + "testing" +) + +const online = "github.com/LensBridge/agent/internal/online" + +func TestCoreDoesNotImportOnline(t *testing.T) { + out, err := exec.Command("go", "list", "-f", + `{{.ImportPath}} {{join .Deps " "}} {{join .TestImports " "}} {{join .XTestImports " "}}`, + "github.com/LensBridge/agent/internal/core/...").CombinedOutput() + if err != nil { + t.Fatalf("go list: %v\n%s", err, out) + } + lines := strings.Split(strings.TrimSpace(string(out)), "\n") + if len(lines) < 10 { + t.Fatalf("go list found only %d core packages:\n%s", len(lines), out) + } + for _, line := range lines { + pkg, deps, _ := strings.Cut(line, " ") + for _, d := range strings.Fields(deps) { + if d == online || strings.HasPrefix(d, online+"/") { + t.Errorf("%s imports %s: the core must not depend on the online layer", pkg, d) + } + } + } +} diff --git a/internal/cdp/cdp.go b/internal/core/kiosk/cdp.go similarity index 94% rename from internal/cdp/cdp.go rename to internal/core/kiosk/cdp.go index ceb8435..9fb6cb4 100644 --- a/internal/cdp/cdp.go +++ b/internal/core/kiosk/cdp.go @@ -1,12 +1,15 @@ -// Package cdp is a minimal Chrome DevTools Protocol client for the few -// methods the agent actually uses against the kiosk Chromium instance: -// Page.reload, Page.navigate, Page.captureScreenshot, Runtime.evaluate, and -// Inspector.enable to tell a crashed renderer from a live one. +// Package kiosk is everything in the agent that touches the kiosk browser: +// a minimal Chrome DevTools Protocol client (this file), the update screen +// driven over it (screen.go), and the watcher that heals a crashed or hung +// page (heal.go). // -// We don't pull in chromedp because we don't drive a browser — we attach to -// an already-running Chromium with --remote-debugging-port=9222 and only -// need a thin JSON-RPC over WS shim. -package cdp +// The CDP client covers the few methods the agent uses against the kiosk +// Chromium instance: Page.reload, Page.navigate, Page.captureScreenshot, +// Runtime.evaluate, and Inspector.enable to tell a crashed renderer from a +// live one. We don't pull in chromedp because we don't drive a browser — we +// attach to an already-running Chromium with --remote-debugging-port=9222 and +// only need a thin JSON-RPC over WS shim. +package kiosk import ( "context" @@ -54,9 +57,9 @@ type Client struct { id atomic.Int64 // monotonic JSON-RPC request id } -// New returns a Client that talks to the given debugger HTTP endpoint +// NewClient returns a Client that talks to the given debugger HTTP endpoint // (e.g. "http://localhost:9222"). Pass "" to use DefaultDebuggerURL. -func New(debuggerURL string) *Client { +func NewClient(debuggerURL string) *Client { if debuggerURL == "" { debuggerURL = DefaultDebuggerURL } @@ -252,7 +255,7 @@ type PageStatus struct { // the way ProbeEvaluate does, so the error says what state the kiosk is in: // - nil: the board is up and answered. // - ErrEvalUndefined: a page answered but has no hook — the local -// enrollment splash, the update screen, or a frontend build older than +// setup screen, the update screen, or a frontend build older than // getStatus(). The page is alive; it just isn't the board. // - ErrPageThrew, ErrPageNavigating: the page is alive. // - ErrPageCrashed, ErrPageUnresponsive: the browser is up and the page is @@ -377,7 +380,7 @@ func probeReadError(ctx context.Context, op string, err error) error { // ErrEvalUndefined means the expression resolved to `undefined`. Usually an // optional call short-circuiting because the page doesn't implement the hook -// (an old frontend build, or the local enrollment splash rather than the +// (an old frontend build, or the local setup screen rather than the // board). Callers decide whether that's fatal. var ErrEvalUndefined = errors.New("cdp: expression evaluated to undefined") diff --git a/internal/cdp/cdp_test.go b/internal/core/kiosk/cdp_test.go similarity index 97% rename from internal/cdp/cdp_test.go rename to internal/core/kiosk/cdp_test.go index fca81b2..45cfa62 100644 --- a/internal/cdp/cdp_test.go +++ b/internal/core/kiosk/cdp_test.go @@ -1,4 +1,4 @@ -package cdp +package kiosk import ( "context" @@ -72,7 +72,7 @@ func newFakeChrome(t *testing.T, reply func(req rpcRequest) []any) *fakeChrome { return f } -func (f *fakeChrome) client() *Client { return New(f.srv.URL) } +func (f *fakeChrome) client() *Client { return NewClient(f.srv.URL) } func (f *fakeChrome) seen() []string { f.mu.Lock() @@ -124,7 +124,7 @@ func TestPageStatusBoardAnswers(t *testing.T) { } } -// The splash, the update screen and old board apps have no getStatus(). +// The setup screen, the update screen and old board apps have no getStatus(). func TestPageStatusNoHook(t *testing.T) { f := newFakeChrome(t, healthy(nil)) if _, err := f.client().PageStatus(probeCtx(t)); !errors.Is(err, ErrEvalUndefined) { diff --git a/internal/core/kiosk/heal.go b/internal/core/kiosk/heal.go new file mode 100644 index 0000000..27a2458 --- /dev/null +++ b/internal/core/kiosk/heal.go @@ -0,0 +1,213 @@ +package kiosk + +import ( + "context" + "errors" + "fmt" + "log/slog" + "os/exec" + "strings" + "time" +) + +// WatchInterval is how often the daemon checks that Chromium is not +// sitting on its own error page. The kiosk is ordered after the agent, so +// this is a backstop, not the mechanism. +const WatchInterval = 30 * time.Second + +// Kiosk self-healing (Watch). The page is probed every +// WatchInterval. A crashed renderer is certain after one probe; a page +// that does not answer may be busy (a large poster decoding on a Pi), so it +// gets kioskHungThreshold probes. Then the watcher reloads the page; if the +// page is still dead after that, it restarts the kiosk unit. Restarts back off +// from kioskRestartMinGap to kioskRestartMaxGap, and the backoff only starts +// over after the page has been healthy for kioskRestartResetAfter, so a page +// that never comes back costs at most one reload and one restart an hour. +const ( + kioskProbeTimeout = 5 * time.Second + kioskCrashThreshold = 1 + kioskHungThreshold = 3 + kioskRestartMinGap = 5 * time.Minute + kioskRestartMaxGap = time.Hour + kioskRestartResetAfter = time.Hour +) + +// Watch keeps the kiosk on the board at boardURL until ctx ends: it +// navigates Chromium back if it lands on its own error page (the server +// restarting under it, for instance) and heals a crashed or hung page +// (healer). updateActive reports whether the update screen is up. +func Watch(ctx context.Context, logger *slog.Logger, c *Client, boardURL string, updateActive func() bool) { + h := newHealer(logger, c, boardURL, updateActive) + t := time.NewTicker(WatchInterval) + defer t.Stop() + for { + select { + case <-ctx.Done(): + return + case <-t.C: + } + h.tick(ctx) + } +} + +// healer is the watcher's state between ticks. Its browser and systemd +// operations are fields so the escalation can be tested without either. +type healer struct { + log *slog.Logger + boardURL string + now func() time.Time + updateActive func() bool + target func(context.Context) (Target, error) + navigate func(context.Context, Target, string) error + health func(context.Context) error + reload func(context.Context) error + restart func(context.Context) error + + fails int // consecutive dead-page probes + reloaded bool // reloaded since the last restart (or since healthy) + restarts int // restarts since the backoff last started over + nextRestart time.Time // no restart before this + healthySince time.Time // zero while the page is dead + waitLogged bool +} + +func newHealer(logger *slog.Logger, c *Client, boardURL string, updateActive func() bool) *healer { + if updateActive == nil { + updateActive = func() bool { return false } + } + return &healer{ + log: logger, + boardURL: boardURL, + now: time.Now, + updateActive: updateActive, + target: c.FirstPageTarget, + navigate: func(ctx context.Context, t Target, url string) error { + return c.Call(ctx, t, "Page.navigate", map[string]any{"url": url}, nil) + }, + health: c.PageHealth, + reload: c.PageReload, + restart: Restart, + } +} + +func (h *healer) tick(ctx context.Context) { + // The update screen is driven over CDP by the importer and may be + // waiting on an agent restart; nothing here may navigate under it. + if h.updateActive() { + h.fails = 0 + return + } + + cctx, cancel := context.WithTimeout(ctx, kioskProbeTimeout) + target, err := h.target(cctx) + cancel() + if err == nil && strings.HasPrefix(target.URL, "chrome-error:") { + h.log.Info("kiosk is on an error page; returning it to the board") + cctx, cancel := context.WithTimeout(ctx, kioskProbeTimeout) + _ = h.navigate(cctx, target, h.boardURL) + cancel() + return + } + if err != nil { + // No browser, or no page yet: starting, or restarting (perhaps + // because we asked). systemd's Restart=always owns that case. + return + } + + cctx, cancel = context.WithTimeout(ctx, kioskProbeTimeout) + err = h.health(cctx) + cancel() + if ctx.Err() != nil { + return + } + + threshold := 0 + switch { + case errors.Is(err, ErrPageCrashed): + threshold = kioskCrashThreshold + case errors.Is(err, ErrPageUnresponsive): + threshold = kioskHungThreshold + case errors.Is(err, ErrDebuggerUnreachable), errors.Is(err, ErrNoPageTarget): + // The browser went away between the two calls: not the page's fault, + // and not proof it recovered either. + return + default: + // Answered, or between documents, or the hook threw: the page is + // alive. A navigation in flight is not a failure. + h.healthy() + return + } + + h.healthySince = time.Time{} + h.fails++ + if h.fails < threshold { + h.log.Warn("kiosk page is not answering", "err", err, "failures", h.fails, "url", target.URL) + return + } + h.heal(ctx, err, target.URL) +} + +func (h *healer) healthy() { + now := h.now() + if h.fails > 0 || h.reloaded { + h.log.Info("kiosk page is answering again") + } + h.fails, h.reloaded, h.waitLogged = 0, false, false + if h.healthySince.IsZero() { + h.healthySince = now + } + if h.restarts > 0 && now.Sub(h.healthySince) >= kioskRestartResetAfter { + h.restarts, h.nextRestart = 0, time.Time{} + } +} + +// heal takes the next step for a dead page: a reload, at most once until the +// page answers again or the kiosk restarts; then a restart, at most once per +// backoff gap. A page that recovers each time it is reloaded is reloaded each +// time it dies, which is what it needs; a page that never recovers gets one +// reload and one restart per gap. +func (h *healer) heal(ctx context.Context, cause error, url string) { + if !h.reloaded { + h.fails, h.reloaded = 0, true + h.log.Warn("kiosk page is dead; reloading it", "err", cause, "url", url) + cctx, cancel := context.WithTimeout(ctx, kioskProbeTimeout) + if err := h.reload(cctx); err != nil { + h.log.Warn("could not reload the kiosk page", "err", err) + } + cancel() + return + } + + now := h.now() + if now.Before(h.nextRestart) { + if !h.waitLogged { + h.log.Error("kiosk page is still dead; waiting before restarting the kiosk again so a broken page cannot restart it in a loop", + "err", cause, "url", url, "nextAttempt", h.nextRestart.Format(time.RFC3339)) + h.waitLogged = true + } + return + } + + h.fails, h.reloaded, h.waitLogged = 0, false, false + gap := min(kioskRestartMinGap< 30 { t.Errorf("%d restarts in a day: the backoff is not holding", r.k.restarts) @@ -149,7 +145,7 @@ func TestKioskHealerBackoffMinimumGap(t *testing.T) { r.want(1, 1) // After the restart the page gets one more reload, then nothing until // kioskRestartMinGap has passed. - r.ticks(int(kioskRestartMinGap/kioskWatchInterval) - 1) + r.ticks(int(kioskRestartMinGap/WatchInterval) - 1) r.want(2, 1) r.ticks(1) r.want(2, 2) @@ -185,7 +181,7 @@ func TestKioskHealerBackoffResetsAfterSustainedHealth(t *testing.T) { r.want(2, 1) // reloaded; the restart is held by the backoff r.k.health = nil - r.ticks(int(kioskRestartResetAfter/kioskWatchInterval) + 1) + r.ticks(int(kioskRestartResetAfter/WatchInterval) + 1) r.k.health = errCrashed r.ticks(2) r.want(3, 2) // reload, then a restart at once: the backoff started over @@ -199,10 +195,10 @@ func TestKioskHealerBackoffResetsAfterSustainedHealth(t *testing.T) { func TestKioskHealerLeavesLegitimateStatesAlone(t *testing.T) { for name, err := range map[string]error{ "board": nil, - "splash or old": cdp.ErrEvalUndefined, - "navigating": fmt.Errorf("%w: Execution context was destroyed.", cdp.ErrPageNavigating), - "hook threw": fmt.Errorf("%w: TypeError", cdp.ErrPageThrew), - "browser gone": fmt.Errorf("%w: ws dial", cdp.ErrDebuggerUnreachable), + "splash or old": ErrEvalUndefined, + "navigating": fmt.Errorf("%w: Execution context was destroyed.", ErrPageNavigating), + "hook threw": fmt.Errorf("%w: TypeError", ErrPageThrew), + "browser gone": fmt.Errorf("%w: ws dial", ErrDebuggerUnreachable), } { t.Run(name, func(t *testing.T) { r := newRig(t) @@ -215,7 +211,7 @@ func TestKioskHealerLeavesLegitimateStatesAlone(t *testing.T) { func TestKioskHealerNoBrowser(t *testing.T) { r := newRig(t) - r.k.targetErr = cdp.ErrDebuggerUnreachable + r.k.targetErr = ErrDebuggerUnreachable r.k.health = errCrashed // never consulted r.ticks(50) r.want(0, 0) @@ -246,34 +242,3 @@ func TestKioskHealerChromeErrorPage(t *testing.T) { } r.want(0, 0) } - -func TestBackendTransport(t *testing.T) { - on := true - cases := []struct { - name string - cfg config.Config - wantErr bool - wantLog string - }{ - {"tls", config.Config{BackendURL: "https://api.example.com", WebSocketURL: "wss://api.example.com/ws"}, false, ""}, - {"http without opt-in", config.Config{BackendURL: "http://10.0.2.2:8080", WebSocketURL: "ws://10.0.2.2:8080/ws"}, true, "REFUSING TO TALK TO THE BACKEND"}, - {"socket elsewhere", config.Config{BackendURL: "https://api.example.com", WebSocketURL: "wss://other.example.com/ws"}, true, "REFUSING TO TALK TO THE BACKEND"}, - {"insecure dev", config.Config{BackendURL: "http://10.0.2.2:8080", WebSocketURL: "ws://10.0.2.2:8080/ws", InsecureDevSet: &on}, false, "INSECURE DEVELOPMENT BOARD"}, - {"insecure dev with tls still warns", config.Config{BackendURL: "https://api.example.com", WebSocketURL: "wss://api.example.com/ws", InsecureDevSet: &on}, false, "INSECURE DEVELOPMENT BOARD"}, - } - for _, tc := range cases { - t.Run(tc.name, func(t *testing.T) { - var buf bytes.Buffer - err := backendTransport(slog.New(slog.NewTextHandler(&buf, nil)), &tc.cfg) - if (err != nil) != tc.wantErr { - t.Errorf("err = %v, want error %v", err, tc.wantErr) - } - if tc.wantLog == "" && buf.Len() != 0 { - t.Errorf("unexpected log: %s", buf.String()) - } - if tc.wantLog != "" && !strings.Contains(buf.String(), tc.wantLog) { - t.Errorf("log %q does not say %q", buf.String(), tc.wantLog) - } - }) - } -} diff --git a/internal/updatescreen/updatescreen.go b/internal/core/kiosk/screen.go similarity index 92% rename from internal/updatescreen/updatescreen.go rename to internal/core/kiosk/screen.go index e75fbf4..f7da7ba 100644 --- a/internal/updatescreen/updatescreen.go +++ b/internal/core/kiosk/screen.go @@ -1,4 +1,4 @@ -// Package updatescreen puts the kiosk on the "Working on updates" screen +// The update screen puts the kiosk on the "Working on updates" screen // (update-anim/index.html, served by the local server at /_mb/updating) while // the importer installs something, shows the outcome, and returns the kiosk to // the board afterwards (docs/architecture.md, section 8). When nothing is @@ -17,7 +17,8 @@ // Every call is best effort. The kiosk may be restarting or absent (a board // without a display attached still takes updates), and an update must never // fail because the screen could not be shown. -package updatescreen + +package kiosk import ( "context" @@ -27,12 +28,11 @@ import ( "sync" "time" - "github.com/LensBridge/agent/internal/cdp" - "github.com/LensBridge/agent/internal/notice" + "github.com/LensBridge/agent/internal/core/notice" ) -// Path is where the local server serves the screen. -const Path = "/_mb/updating" +// ScreenPath is where the local server serves the update screen. +const ScreenPath = "/_mb/updating" // callTimeout bounds one CDP round trip. const callTimeout = 5 * time.Second @@ -56,7 +56,7 @@ const fadeOutScript = `new Promise(function (done) { // Screen implements importer.Screen. type Screen struct { - cdp *cdp.Client + cdp *Client baseURL string // e.g. http://127.0.0.1:8080 logger *slog.Logger @@ -68,9 +68,9 @@ type Screen struct { carry *notice.Notice } -// New returns a Screen for the kiosk at the default CDP endpoint, whose board -// is served at baseURL. -func New(c *cdp.Client, baseURL string, logger *slog.Logger) *Screen { +// NewScreen returns a Screen for the kiosk reached through c, whose board is +// served at baseURL. +func NewScreen(c *Client, baseURL string, logger *slog.Logger) *Screen { return &Screen{cdp: c, baseURL: strings.TrimRight(baseURL, "/"), logger: logger} } @@ -98,7 +98,7 @@ func (s *Screen) Begin(ctx context.Context) { return } s.fadeOut(ctx) - if err := s.navigate(ctx, s.baseURL+Path); err != nil { + if err := s.navigate(ctx, s.baseURL+ScreenPath); err != nil { s.logger.Debug("update screen: navigate failed", "err", err) return } @@ -126,7 +126,7 @@ func (s *Screen) Caption(ctx context.Context, text string) { } // Restarting says the agent is about to be replaced. The screen stays up and -// working; the next agent finishes it (package agentupdate). +// working; the next agent finishes it (selfupdate.Reporter). func (s *Screen) Restarting(ctx context.Context) { s.Caption(ctx, "Restarting MusallahBoard") } @@ -190,7 +190,7 @@ func (s *Screen) OnScreen(ctx context.Context) bool { cctx, cancel := context.WithTimeout(ctx, callTimeout) defer cancel() target, err := s.cdp.FirstPageTarget(cctx) - return err == nil && strings.Contains(target.URL, Path) + return err == nil && strings.Contains(target.URL, ScreenPath) } // merge combines a held outcome with the one that followed it: the more diff --git a/internal/localserver/server.go b/internal/core/localserver/server.go similarity index 70% rename from internal/localserver/server.go rename to internal/core/localserver/server.go index b8c7836..e250304 100644 --- a/internal/localserver/server.go +++ b/internal/core/localserver/server.go @@ -24,12 +24,14 @@ import ( "strings" "time" - "github.com/LensBridge/agent/internal/clock" - "github.com/LensBridge/agent/internal/events" - "github.com/LensBridge/agent/internal/mbu" - "github.com/LensBridge/agent/internal/store" - "github.com/LensBridge/agent/internal/updates" - "github.com/LensBridge/agent/internal/updatescreen" + "github.com/LensBridge/agent/internal/core/clock" + "github.com/LensBridge/agent/internal/core/config" + "github.com/LensBridge/agent/internal/core/events" + "github.com/LensBridge/agent/internal/core/kiosk" + "github.com/LensBridge/agent/internal/core/mbu" + "github.com/LensBridge/agent/internal/core/netinfo" + "github.com/LensBridge/agent/internal/core/store" + "github.com/LensBridge/agent/internal/core/updates" updateanim "github.com/LensBridge/agent/update-anim" ) @@ -50,8 +52,9 @@ const ( // Deps is what the server reads. type Deps struct { - Layout store.Layout - DeviceID string + Layout store.Layout + // Config is agent.toml: the board's identity and offline routes. + Config *config.Live AgentVersion string Hub *events.Hub // Sync returns the sync status object for /api/local/status. May be nil. @@ -64,8 +67,6 @@ type Deps struct { Updates func() updates.Info // Clock says whether the board's clock can be believed. May be nil. Clock func() clock.Info - // ServicePort and USBImport are the board's offline routes (agent.toml). - ServicePort, USBImport bool // Backend reports the backend connection (wsclient.ConnState), or nil // when there is none. May be nil. Backend func() any @@ -87,6 +88,9 @@ func New(d Deps) *Server { if d.Hub == nil { d.Hub = &events.Hub{} } + if d.Config == nil { + d.Config = config.InMemory(config.Config{}) + } return &Server{d: d} } @@ -121,6 +125,12 @@ func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) { writeJSON(w, http.StatusOK, s.Status()) case p == "/api/local/events": s.d.Hub.ServeHTTP(w, r) + case p == "/api/local/where": + // The setup screen's address line, refetched while the board waits + // for its setup stick, so a DHCP lease or a cable plugged in later + // shows up without a reload. + w.Header().Set("Cache-Control", cacheNoStore) + writeJSON(w, http.StatusOK, map[string]string{"where": where(netinfo.Collect(r.Context()))}) case strings.HasPrefix(p, "/api/"): writeJSONError(w, http.StatusNotFound, "not found") case strings.HasPrefix(p, "/media/"): @@ -132,7 +142,7 @@ func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) { w.Header().Set("Cache-Control", cacheNoStore) w.Header().Set("Content-Type", "image/gif") _, _ = w.Write(aliveGIF) - case p == updatescreen.Path: + case p == kiosk.ScreenPath: w.Header().Set("Cache-Control", cacheNoStore) w.Header().Set("Content-Type", "text/html; charset=utf-8") _, _ = w.Write(updateanim.HTML) @@ -143,8 +153,10 @@ func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) { // Status is the current /api/local/status object. func (s *Server) Status() Status { - st := BuildStatus(s.d.Layout, s.d.DeviceID, s.d.AgentVersion, s.d.Now()) - st.ServicePort, st.USBImport = s.d.ServicePort, s.d.USBImport + cfg := s.d.Config.Get() + st := BuildStatus(s.d.Layout, cfg.DeviceID, s.d.AgentVersion, s.d.Now()) + st.DisplayName = cfg.DisplayName + st.ServicePort, st.USBImport = cfg.ServicePort(), cfg.USBImport() if s.d.Backend != nil { st.Backend = s.d.Backend() } @@ -185,23 +197,31 @@ func (s *Server) handlePayload(w http.ResponseWriter, _ *http.Request) { writeJSONError(w, http.StatusInternalServerError, "payload missing from installed content") return } + // Run-out (spec C6): past the bundle's last day the board keeps + // serving that day, and says so, so the page can drop what is dated. + expired, _ := json.Marshal(day.StaleDays > 0) + lastDay, _ := json.Marshal(c.Manifest.Content.LastDay) + fields := map[string]json.RawMessage{"expired": expired, "lastDay": lastDay} if s.d.Weather != nil { if weather, ok := s.d.Weather(); ok { - raw = overlayWeather(raw, weather) + fields["weather"] = weather } } w.Header().Set("Content-Type", "application/json") - _, _ = w.Write(raw) + _, _ = w.Write(overlay(raw, fields)) } -// overlayWeather replaces the payload's weather with a live one. Only the one -// key changes; if the payload cannot be re-encoded it is served untouched. -func overlayWeather(raw, weather []byte) []byte { +// overlay sets top-level keys of the payload object: the run-out fields and +// a live weather object. Nothing else changes; a payload that cannot be +// re-encoded is served untouched. +func overlay(raw []byte, fields map[string]json.RawMessage) []byte { var obj map[string]json.RawMessage if err := json.Unmarshal(raw, &obj); err != nil { return raw } - obj["weather"] = weather + for k, v := range fields { + obj[k] = v + } out, err := json.Marshal(obj) if err != nil { return raw @@ -247,6 +267,14 @@ func (s *Server) handleMedia(w http.ResponseWriter, r *http.Request) { // /assets/ file is a 404 instead: it is hashed build output, and HTML under an // immutable cache header for a stale script URL is worse than an honest miss. func (s *Server) handleApp(w http.ResponseWriter, r *http.Request) { + if !s.d.Config.Get().Provisioned() { + // Whatever is installed, an unprovisioned board says so and nothing + // else: it does not know which board it is. + w.Header().Set("Cache-Control", cacheNoStore) + w.Header().Set("Content-Type", "text/html; charset=utf-8") + _, _ = io.WriteString(w, setupPage(netinfo.Collect(r.Context()))) + return + } a, err := s.d.Layout.CurrentApp() if err != nil { w.Header().Set("Cache-Control", cacheNoStore) @@ -335,11 +363,12 @@ func writeJSONError(w http.ResponseWriter, code int, msg string) { // appears on its own once an app package lands. It suggests only the offline // routes this board accepts. func (s *Server) noAppPage() string { + cfg := s.d.Config.Get() var routes []string - if s.d.USBImport { + if cfg.USBImport() { routes = append(routes, "plug in a USB stick holding a MusallahBoard update") } - if s.d.ServicePort { + if cfg.ServicePort() { routes = append(routes, "connect a laptop or phone to the board's ethernet port and open http://10.77.0.1/") } offline := "Without internet, it needs to be set up for USB sticks or its ethernet service port first." @@ -349,6 +378,44 @@ func (s *Server) noAppPage() string { return strings.Replace(noAppHTML, "{{offline}}", html.EscapeString(offline), 1) } +// setupPage is the board's screen until a setup file (provision package) has +// given it an identity. The address line is for a maintainer with SSH. It +// shows the banners an import raises ("Reading USB stick", and the outcome), +// and reloads once the board is set up. +func setupPage(n netinfo.Info) string { + return strings.Replace(setupHTML, "{{where}}", html.EscapeString(where(n)), 1) +} + +// where is the setup screen's address line: hostname and IPv4 addresses. +func where(n netinfo.Info) string { + w := n.Hostname + if len(n.IPv4) > 0 { + w += " · " + strings.Join(n.IPv4, ", ") + } + return w +} + +const setupHTML = ` +MusallahBoard + +

This board is not set up yet

+

Plug in its setup USB stick.

{{where}} +` + // aliveGIF is a transparent 1x1 GIF. var aliveGIF = []byte("GIF89a\x01\x00\x01\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00" + "!\xf9\x04\x01\x00\x00\x00\x00,\x00\x00\x00\x00\x01\x00\x01\x00\x00\x02\x02D\x01\x00;") diff --git a/internal/localserver/server_test.go b/internal/core/localserver/server_test.go similarity index 64% rename from internal/localserver/server_test.go rename to internal/core/localserver/server_test.go index 643eae4..a8b2cd4 100644 --- a/internal/localserver/server_test.go +++ b/internal/core/localserver/server_test.go @@ -5,7 +5,7 @@ import ( "context" "crypto/ed25519" "encoding/json" - "github.com/LensBridge/agent/internal/clock" + "github.com/LensBridge/agent/internal/core/netinfo" "net/http" "net/http/httptest" "os" @@ -14,10 +14,12 @@ import ( "testing" "time" - "github.com/LensBridge/agent/internal/importer" - "github.com/LensBridge/agent/internal/mbu" - "github.com/LensBridge/agent/internal/store" - "github.com/LensBridge/agent/internal/trust" + "github.com/LensBridge/agent/internal/core/clock" + "github.com/LensBridge/agent/internal/core/config" + "github.com/LensBridge/agent/internal/core/importer" + "github.com/LensBridge/agent/internal/core/mbu" + "github.com/LensBridge/agent/internal/core/store" + "github.com/LensBridge/agent/internal/core/trust" ) const dev = "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b" @@ -43,7 +45,7 @@ func installed(t *testing.T) store.Layout { t.Helper() l := store.Layout{Root: t.TempDir()} ring := trust.NewRing([]ed25519.PublicKey{ck.Public().(ed25519.PublicKey)}, []ed25519.PublicKey{rk.Public().(ed25519.PublicKey)}) - im := importer.New(importer.Deps{Layout: l, DeviceID: dev, AgentVersion: "0.2.0", + im := importer.New(importer.Deps{Layout: l, Config: config.InMemory(config.Config{DeviceID: dev}), AgentVersion: "0.2.0", Ring: func() (*trust.Ring, error) { return ring, nil }}) c := pkg(t, mbu.Manifest{Type: mbu.TypeContent, Sequence: 1, DeviceID: dev, Content: &mbu.ContentInfo{Timezone: "America/Toronto", FirstDay: "2026-09-24", LastDay: "2026-09-25"}}, @@ -78,7 +80,7 @@ func TestPayloadPicksDayAndClamps(t *testing.T) { day int want string }{{23, `"day":24`}, {24, `"day":24`}, {25, `"day":25`}, {28, `"day":25`}} { - s := New(Deps{Layout: l, DeviceID: dev, Now: at(c.day, 12)}) + s := New(Deps{Layout: l, Config: config.InMemory(config.Config{DeviceID: dev}), Now: at(c.day, 12)}) w := get(t, s, "/api/musallah/payload") if w.Code != 200 || !strings.Contains(w.Body.String(), c.want) { t.Errorf("day %d: %d %s", c.day, w.Code, w.Body) @@ -86,9 +88,31 @@ func TestPayloadPicksDayAndClamps(t *testing.T) { } } +// Past its last day (2026-09-25) the board serves that day, marked expired. +func TestPayloadRunOut(t *testing.T) { + l := installed(t) + for day, want := range map[int]bool{24: false, 25: false, 26: true, 40: true} { + s := New(Deps{Layout: l, Config: config.InMemory(config.Config{DeviceID: dev}), Now: at(day, 12)}) + var p struct { + Day int `json:"day"` + Expired *bool `json:"expired"` + LastDay *string `json:"lastDay"` + } + if err := json.Unmarshal(get(t, s, "/api/musallah/payload").Body.Bytes(), &p); err != nil { + t.Fatal(err) + } + if p.Expired == nil || *p.Expired != want || p.LastDay == nil || *p.LastDay != "2026-09-25" { + t.Errorf("day %d: expired=%v lastDay=%v, want expired=%v lastDay 2026-09-25", day, p.Expired, p.LastDay, want) + } + if want && p.Day != 25 { + t.Errorf("day %d: served day %d, want the last one", day, p.Day) + } + } +} + func TestWeatherOverlay(t *testing.T) { l := installed(t) - s := New(Deps{Layout: l, DeviceID: dev, Now: at(24, 12), + s := New(Deps{Layout: l, Config: config.InMemory(config.Config{DeviceID: dev}), Now: at(24, 12), Weather: func() (json.RawMessage, bool) { return json.RawMessage(`{"tempC":12}`), true }}) if w := get(t, s, "/api/musallah/payload"); !strings.Contains(w.Body.String(), `"weather":{"tempC":12}`) { t.Fatalf("overlay missing: %s", w.Body) @@ -96,7 +120,7 @@ func TestWeatherOverlay(t *testing.T) { } func TestNoContentNoApp(t *testing.T) { - s := New(Deps{Layout: store.Layout{Root: t.TempDir()}, DeviceID: dev}) + s := New(Deps{Layout: store.Layout{Root: t.TempDir()}, Config: config.InMemory(config.Config{DeviceID: dev})}) if w := get(t, s, "/api/musallah/payload"); w.Code != 503 || !strings.Contains(w.Body.String(), "no content installed") { t.Errorf("payload without content: %d %s", w.Code, w.Body) } @@ -111,7 +135,7 @@ func TestNoContentNoApp(t *testing.T) { } func TestAppServing(t *testing.T) { - s := New(Deps{Layout: installed(t), DeviceID: dev, Now: at(24, 12)}) + s := New(Deps{Layout: installed(t), Config: config.InMemory(config.Config{DeviceID: dev}), Now: at(24, 12)}) if w := get(t, s, "/"); !strings.Contains(w.Body.String(), "board") || w.Header().Get("Cache-Control") != cacheNoCache { t.Errorf("index: %s %v", w.Body, w.Header()) } @@ -141,7 +165,7 @@ func TestAppServing(t *testing.T) { } func TestStatus(t *testing.T) { - s := New(Deps{Layout: installed(t), DeviceID: dev, AgentVersion: "0.2.0", Now: at(25, 12), + s := New(Deps{Layout: installed(t), Config: config.InMemory(config.Config{DeviceID: dev}), AgentVersion: "0.2.0", Now: at(25, 12), Sync: func() any { return map[string]bool{"enabled": true} }}) var st Status json.Unmarshal(get(t, s, "/api/local/status").Body.Bytes(), &st) @@ -182,7 +206,8 @@ func TestNoAppPageOffersOnlyWorkingRoutes(t *testing.T) { {false, false, []string{"set up for USB sticks or its ethernet service port first"}, []string{"10.77.0.1"}}, } for _, tc := range cases { - page := (&Server{d: Deps{USBImport: tc.usb, ServicePort: tc.port}}).noAppPage() + cfg := config.Config{USBImportSet: &tc.usb, ServicePortSet: &tc.port} + page := New(Deps{Config: config.InMemory(cfg)}).noAppPage() for _, w := range tc.want { if !strings.Contains(page, w) { t.Errorf("usb=%v port=%v: missing %q", tc.usb, tc.port, w) @@ -195,3 +220,42 @@ func TestNoAppPageOffersOnlyWorkingRoutes(t *testing.T) { } } } + +// An unprovisioned board shows its setup screen at every page path, whatever +// is installed, and still serves its API. +func TestUnprovisionedBoardShowsSetupScreen(t *testing.T) { + s := New(Deps{Layout: installed(t), Now: at(24, 12)}) + for _, path := range []string{"/", "/some/route"} { + rec := httptest.NewRecorder() + s.ServeHTTP(rec, httptest.NewRequest("GET", path, nil)) + if rec.Code != 200 || !strings.Contains(rec.Body.String(), "This board is not set up yet") { + t.Fatalf("%s: %d %.80q", path, rec.Code, rec.Body.String()) + } + } + rec := httptest.NewRecorder() + s.ServeHTTP(rec, httptest.NewRequest("GET", "/api/local/status", nil)) + if rec.Code != 200 || !strings.Contains(rec.Body.String(), `"deviceId":""`) { + t.Fatalf("status: %d %s", rec.Code, rec.Body.String()) + } + // The address line is refetched, so a later DHCP lease or cable shows up. + rec = httptest.NewRecorder() + s.ServeHTTP(rec, httptest.NewRequest("GET", "/api/local/where", nil)) + var w struct{ Where string } + if rec.Code != 200 || json.Unmarshal(rec.Body.Bytes(), &w) != nil || w.Where == "" { + t.Fatalf("where: %d %s", rec.Code, rec.Body.String()) + } +} + +func TestWhere(t *testing.T) { + for _, tc := range []struct { + n netinfo.Info + want string + }{ + {netinfo.Info{Hostname: "mb-1"}, "mb-1"}, + {netinfo.Info{Hostname: "mb-1", IPv4: []string{"10.0.0.5", "192.168.1.9"}}, "mb-1 · 10.0.0.5, 192.168.1.9"}, + } { + if got := where(tc.n); got != tc.want { + t.Errorf("where(%+v) = %q, want %q", tc.n, got, tc.want) + } + } +} diff --git a/internal/localserver/status.go b/internal/core/localserver/status.go similarity index 91% rename from internal/localserver/status.go rename to internal/core/localserver/status.go index 3dab340..701f818 100644 --- a/internal/localserver/status.go +++ b/internal/core/localserver/status.go @@ -5,19 +5,21 @@ import ( "errors" "time" - "github.com/LensBridge/agent/internal/clock" - "github.com/LensBridge/agent/internal/importer" - "github.com/LensBridge/agent/internal/selfupdate" - "github.com/LensBridge/agent/internal/store" - "github.com/LensBridge/agent/internal/updates" + "github.com/LensBridge/agent/internal/core/clock" + "github.com/LensBridge/agent/internal/core/importer" + "github.com/LensBridge/agent/internal/core/selfupdate" + "github.com/LensBridge/agent/internal/core/store" + "github.com/LensBridge/agent/internal/core/updates" ) // Status is /api/local/status (docs/architecture.md, section 7). The CLI and // the upload server build theirs from it. type Status struct { - LocalAPI int `json:"localApi"` - AgentVersion string `json:"agentVersion"` - DeviceID string `json:"deviceId"` + LocalAPI int `json:"localApi"` + AgentVersion string `json:"agentVersion"` + DeviceID string `json:"deviceId"` + // DisplayName is the board's name from its setup file, if it has one. + DisplayName string `json:"displayName,omitempty"` App *AppInfo `json:"app"` Content *ContentInfo `json:"content"` Today string `json:"today"` diff --git a/internal/mbu/manifest.go b/internal/core/mbu/manifest.go similarity index 96% rename from internal/mbu/manifest.go rename to internal/core/mbu/manifest.go index 3fd18c2..b555f3a 100644 --- a/internal/mbu/manifest.go +++ b/internal/core/mbu/manifest.go @@ -48,7 +48,7 @@ const ( MaxTotalBytes = 1 << 30 MaxPayloadBytes = 16 << 20 MaxMediaBytes = 512 << 20 - MaxContentDays = 31 + MaxContentDays = 92 // a quarter: an offline board visited every few months maxPathBytes = 200 maxPathSegments = 8 ) @@ -60,6 +60,9 @@ const ( TypeContent Type = "content" TypeApp Type = "app" TypeAgent Type = "agent" + // TypeProvision is a setup file: a board's identity and, optionally, its + // backend (provision.go). Signed by a content key. + TypeProvision Type = "provision" ) // File is one entry of the manifest's files list. @@ -154,6 +157,8 @@ func (m *Manifest) Describe() string { return "board app " + m.Version case TypeAgent: return "agent " + m.Version + case TypeProvision: + return "setup file for " + m.DeviceID } return string(m.Type) } @@ -293,8 +298,10 @@ func ParseManifest(raw []byte) (*Manifest, error) { err = m.checkApp() case TypeAgent: err = m.checkAgent() + case TypeProvision: + err = m.checkProvision() default: - err = fmt.Errorf("mbu.json type %q is not content, app or agent", m.Type) + err = fmt.Errorf("mbu.json type %q is not content, app, agent or provision", m.Type) } if err != nil { return nil, err diff --git a/internal/mbu/mbu_test.go b/internal/core/mbu/mbu_test.go similarity index 77% rename from internal/mbu/mbu_test.go rename to internal/core/mbu/mbu_test.go index 0a846b6..71efdc3 100644 --- a/internal/mbu/mbu_test.go +++ b/internal/core/mbu/mbu_test.go @@ -5,15 +5,17 @@ import ( "bytes" "crypto/ed25519" "crypto/sha256" + "encoding/base64" "encoding/hex" "errors" + "fmt" "os" "path/filepath" "strings" "testing" "time" - "github.com/LensBridge/agent/internal/trust" + "github.com/LensBridge/agent/internal/core/trust" ) const testDevice = "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b" @@ -290,3 +292,52 @@ func TestKeyIDVector(t *testing.T) { } t.Logf("seed 0x01..0x20 -> keyId %s", id) } + +func TestProvisionManifestRules(t *testing.T) { + base := `{"format":"mbu","formatVersion":2,"type":"provision","createdAt":"2026-11-19T12:00:00Z","sequence":5,"deviceId":"` + testDevice + `","files":[%s]}` + one := `{"path":"provision.json","sha256":"` + strings.Repeat("a", 64) + `","bytes":10}` + if _, err := ParseManifest([]byte(fmt.Sprintf(base, one))); err != nil { + t.Fatalf("valid provision manifest: %v", err) + } + two := one + `,{"path":"run.sh","sha256":"` + strings.Repeat("b", 64) + `","bytes":10}` + if _, err := ParseManifest([]byte(fmt.Sprintf(base, two))); err == nil { + t.Fatal("a provision package with another file was accepted") + } + if RoleFor(TypeProvision) != trust.RoleContent { + t.Fatal("setup files must be signed by a content key, never a release key") + } +} + +func TestParseProvision(t *testing.T) { + m := &Manifest{DeviceID: testDevice, Sequence: 5} + secret := base64.RawURLEncoding.EncodeToString(bytes.Repeat([]byte{1}, 32)) + ok := func(s string) bool { _, err := ParseProvision([]byte(s), m); return err == nil } + id := `"deviceId":"` + testDevice + `","sequence":5` + for s, want := range map[string]bool{ + `{"format":1,` + id + `,"displayName":"N"}`: true, + `{"format":1,` + id + `,"backendUrl":"https://api.example.org","claimSecret":"` + secret + `"}`: true, + `{"format":1,` + id + `,"backendUrl":"https://api.example.org","claimSecret":"` + secret + `="}`: true, + `{"format":1,` + id + `,"backendUrl":"https://api.example.org"}`: false, + `{"format":1,` + id + `,"claimSecret":"` + secret + `"}`: false, + `{"format":1,` + id + `,"backendUrl":"ftp://x","claimSecret":"` + secret + `"}`: false, + `{"format":1,` + id + `,"backendUrl":"https://api.example.org","claimSecret":"short"}`: false, + `{"format":2,` + id + `}`: false, + `{"format":1,"deviceId":"` + testDevice + `","sequence":6}`: false, + `{"format":1,"deviceId":"00000000-0000-0000-0000-000000000001","sequence":5}`: false, + } { + if got := ok(s); got != want { + t.Errorf("%s: ok = %v, want %v", s, got, want) + } + } +} + +func TestContentDaysBound(t *testing.T) { + first := "2026-01-01" + for days, ok := range map[int]bool{92: true, 93: false} { + last := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC).AddDate(0, 0, days-1).Format(DateLayout) + _, err := (&ContentInfo{FirstDay: first, LastDay: last}).Days() + if (err == nil) != ok { + t.Errorf("%d days: err = %v", days, err) + } + } +} diff --git a/internal/core/mbu/provision.go b/internal/core/mbu/provision.go new file mode 100644 index 0000000..fe4bc4c --- /dev/null +++ b/internal/core/mbu/provision.go @@ -0,0 +1,108 @@ +package mbu + +import ( + "encoding/base64" + "encoding/json" + "fmt" + "net/url" + "strings" + "time" +) + +// A provision package ("setup file", docs/architecture.md section 4.1) gives a +// board its identity: which device it is, its display name and, for a board +// that will be online, its backend and a one-time claim secret. It is made by +// the backend and signed with the content key, and carries exactly one file, +// provision.json. It can never carry keys, software or anything executable: +// the content key may only ever affect content and identity. + +// ProvisionFile is the one file in a provision package. +const ProvisionFile = "provision.json" + +// MaxProvisionBytes bounds provision.json. +const MaxProvisionBytes = 64 << 10 + +// ProvisionFormat is the provision.json format this agent reads. +const ProvisionFormat = 1 + +// ClaimSecretBytes is the size of a claim secret. +const ClaimSecretBytes = 32 + +// Provision is provision.json. +type Provision struct { + Format int `json:"format"` + DeviceID string `json:"deviceId"` + DisplayName string `json:"displayName"` + Sequence int64 `json:"sequence"` + IssuedAt string `json:"issuedAt,omitempty"` + // BackendURL is absent for a board that stays offline. + BackendURL string `json:"backendUrl,omitempty"` + // ClaimSecret (base64url, 32 bytes) is present exactly when BackendURL + // is. + ClaimSecret string `json:"claimSecret,omitempty"` +} + +func (m *Manifest) checkProvision() error { + if !uuidLikeRE.MatchString(m.DeviceID) { + return fmt.Errorf("provision package has no valid deviceId") + } + if m.Sequence <= 0 { + return fmt.Errorf("provision package has no positive sequence") + } + if len(m.Files) != 1 || m.Files[0].Path != ProvisionFile { + return fmt.Errorf("provision package must list exactly one file, %s", ProvisionFile) + } + if m.Files[0].Bytes > MaxProvisionBytes { + return fmt.Errorf("%s is larger than %d KiB", ProvisionFile, MaxProvisionBytes>>10) + } + return nil +} + +// ParseProvision decodes provision.json from a verified provision package +// with manifest m, and checks it: it must name the same device and sequence +// as the signed manifest, and carry a backend URL and a claim secret together +// or neither. +func ParseProvision(raw []byte, m *Manifest) (*Provision, error) { + var p Provision + if err := json.Unmarshal(raw, &p); err != nil { + return nil, fmt.Errorf("%s is not valid JSON: %w", ProvisionFile, err) + } + switch { + case p.Format != ProvisionFormat: + return nil, fmt.Errorf("%s format %d is not supported by this agent (it reads %d)", ProvisionFile, p.Format, ProvisionFormat) + case !strings.EqualFold(p.DeviceID, m.DeviceID): + return nil, fmt.Errorf("%s is for device %s, its manifest for %s", ProvisionFile, p.DeviceID, m.DeviceID) + case p.Sequence != m.Sequence: + return nil, fmt.Errorf("%s has sequence %d, its manifest %d", ProvisionFile, p.Sequence, m.Sequence) + case len(p.DisplayName) > 200 || strings.ContainsAny(p.DisplayName, "\n\r\x00"): + return nil, fmt.Errorf("%s has an unusable displayName", ProvisionFile) + case (p.BackendURL == "") != (p.ClaimSecret == ""): + return nil, fmt.Errorf("%s must carry backendUrl and claimSecret together, or neither", ProvisionFile) + } + if p.IssuedAt != "" { + if _, err := time.Parse(time.RFC3339, p.IssuedAt); err != nil { + return nil, fmt.Errorf("%s issuedAt %q is not an RFC 3339 time", ProvisionFile, p.IssuedAt) + } + } + if p.BackendURL != "" { + u, err := url.Parse(p.BackendURL) + if err != nil || (u.Scheme != "https" && u.Scheme != "http") || u.Host == "" || u.User != nil || u.RawQuery != "" || u.Fragment != "" { + return nil, fmt.Errorf("%s backendUrl %q is not a plain http(s) base URL", ProvisionFile, p.BackendURL) + } + p.BackendURL = strings.TrimRight(p.BackendURL, "/") + if _, err := DecodeClaimSecret(p.ClaimSecret); err != nil { + return nil, fmt.Errorf("%s: %w", ProvisionFile, err) + } + } + p.DeviceID = m.DeviceID + return &p, nil +} + +// DecodeClaimSecret decodes a base64url claim secret, padded or not. +func DecodeClaimSecret(s string) ([]byte, error) { + b, err := base64.RawURLEncoding.DecodeString(strings.TrimRight(s, "=")) + if err != nil || len(b) != ClaimSecretBytes { + return nil, fmt.Errorf("claimSecret is not %d bytes of base64url", ClaimSecretBytes) + } + return b, nil +} diff --git a/internal/mbu/reader.go b/internal/core/mbu/reader.go similarity index 97% rename from internal/mbu/reader.go rename to internal/core/mbu/reader.go index 8415639..da40e80 100644 --- a/internal/mbu/reader.go +++ b/internal/core/mbu/reader.go @@ -16,7 +16,7 @@ import ( "sort" "strings" - "github.com/LensBridge/agent/internal/trust" + "github.com/LensBridge/agent/internal/core/trust" ) // ErrNotAuthentic means no signature on the package verified under a key @@ -28,9 +28,11 @@ type KeyRing interface { Keys(role trust.Role) map[string]ed25519.PublicKey } -// RoleFor is the key role that may sign packages of type t. +// RoleFor is the key role that may sign packages of type t. Content keys sign +// what the backend makes (content and setup files); everything else is +// software and needs a release key. func RoleFor(t Type) trust.Role { - if t == TypeContent { + if t == TypeContent || t == TypeProvision { return trust.RoleContent } return trust.RoleRelease diff --git a/internal/mbu/writer.go b/internal/core/mbu/writer.go similarity index 98% rename from internal/mbu/writer.go rename to internal/core/mbu/writer.go index a307c90..7470b77 100644 --- a/internal/mbu/writer.go +++ b/internal/core/mbu/writer.go @@ -14,7 +14,7 @@ import ( "strings" "time" - "github.com/LensBridge/agent/internal/trust" + "github.com/LensBridge/agent/internal/core/trust" ) // Source is one file to put in a package. diff --git a/internal/core/netinfo/http.go b/internal/core/netinfo/http.go new file mode 100644 index 0000000..2ea9a62 --- /dev/null +++ b/internal/core/netinfo/http.go @@ -0,0 +1,35 @@ +package netinfo + +import ( + "net" + "net/http" + "time" +) + +// NewHTTPClient is the client every request off the board uses (content +// sync, the release channels): a bounded connect so a board with no route +// gives up fast, and an overall limit long enough for a large package on a +// slow link. +// +// HTTP/2 connections are health-checked with pings. Without them a +// connection that died silently (a NAT or firewall dropping it, a Wi-Fi +// roam) stays in the pool, and every request to that host waits on it until +// ResponseHeaderTimeout ("http2: timeout awaiting response headers"). +func NewHTTPClient() *http.Client { + return &http.Client{ + Timeout: 10 * time.Minute, + Transport: &http.Transport{ + Proxy: http.ProxyFromEnvironment, + DialContext: (&net.Dialer{Timeout: 15 * time.Second, KeepAlive: 30 * time.Second}).DialContext, + TLSHandshakeTimeout: 15 * time.Second, + ResponseHeaderTimeout: 2 * time.Minute, + IdleConnTimeout: 90 * time.Second, + MaxIdleConns: 4, + ForceAttemptHTTP2: true, + HTTP2: &http.HTTP2Config{ + SendPingTimeout: 30 * time.Second, + PingTimeout: 15 * time.Second, + }, + }, + } +} diff --git a/internal/netinfo/netinfo.go b/internal/core/netinfo/netinfo.go similarity index 81% rename from internal/netinfo/netinfo.go rename to internal/core/netinfo/netinfo.go index f641130..d05b74a 100644 --- a/internal/netinfo/netinfo.go +++ b/internal/core/netinfo/netinfo.go @@ -6,7 +6,7 @@ // // - telemetry's heartbeat, via IPv4Addrs — reports every non-loopback IPv4 // the box holds, because the backend wants the raw picture. -// - the pre-enrollment splash, via Collect — reports only addresses an +// - the "not set up yet" screen, via Collect — reports only addresses an // operator can actually connect to, because that address is printed on // the screen as an instruction. package netinfo @@ -16,7 +16,6 @@ import ( "net" "os" "os/exec" - "slices" "strings" "time" ) @@ -28,15 +27,6 @@ type Info struct { Hostname string `json:"hostname,omitempty"` } -// Equal reports whether two snapshots describe the same network state. Used to -// keep a polling loop from logging the same address every few seconds. -func (i Info) Equal(o Info) bool { - return i.SSID == o.SSID && i.Hostname == o.Hostname && slices.Equal(i.IPv4, o.IPv4) -} - -// Online reports whether the device holds at least one usable address. -func (i Info) Online() bool { return len(i.IPv4) > 0 } - // Collect gathers a snapshot for display. Every field is best-effort: a // failure anywhere leaves that field empty rather than failing the call. func Collect(ctx context.Context) Info { @@ -63,7 +53,7 @@ func IPv4Addrs() []string { // routableIPv4 drops 169.254.0.0/16. A link-local address means DHCP never // answered: the interface is "up" and the box has an IP, but nothing on the -// LAN can reach it. Printing one on the enrollment splash would send an +// LAN can reach it. Printing one on the setup screen would send an // operator off to SSH into an address that cannot work. func routableIPv4(ips []string) []string { var out []string diff --git a/internal/core/netinfo/netinfo_test.go b/internal/core/netinfo/netinfo_test.go new file mode 100644 index 0000000..d3f0c0a --- /dev/null +++ b/internal/core/netinfo/netinfo_test.go @@ -0,0 +1,51 @@ +package netinfo + +import ( + "slices" + "testing" +) + +func TestRoutableIPv4DropsLinkLocal(t *testing.T) { + tests := []struct { + name string + in []string + want []string + }{ + { + name: "keeps private lan addresses", + in: []string{"192.168.1.42", "10.0.0.7", "172.16.3.1"}, + want: []string{"192.168.1.42", "10.0.0.7", "172.16.3.1"}, + }, + { + // A 169.254.x address means DHCP never answered. Nothing on the LAN + // can reach it, so it must never reach the setup screen. + name: "drops apipa", + in: []string{"169.254.11.9", "192.168.1.42"}, + want: []string{"192.168.1.42"}, + }, + { + name: "apipa only yields nothing", + in: []string{"169.254.11.9"}, + want: nil, + }, + { + name: "drops unparseable", + in: []string{"not-an-ip", "192.168.1.42"}, + want: []string{"192.168.1.42"}, + }, + { + name: "empty input", + in: nil, + want: nil, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := routableIPv4(tt.in) + if !slices.Equal(got, tt.want) { + t.Errorf("routableIPv4(%v) = %v, want %v", tt.in, got, tt.want) + } + }) + } +} diff --git a/internal/notice/notice.go b/internal/core/notice/notice.go similarity index 100% rename from internal/notice/notice.go rename to internal/core/notice/notice.go diff --git a/internal/notice/notice_test.go b/internal/core/notice/notice_test.go similarity index 100% rename from internal/notice/notice_test.go rename to internal/core/notice/notice_test.go diff --git a/internal/selfupdate/open_unix.go b/internal/core/selfupdate/open_unix.go similarity index 100% rename from internal/selfupdate/open_unix.go rename to internal/core/selfupdate/open_unix.go diff --git a/internal/selfupdate/open_windows.go b/internal/core/selfupdate/open_windows.go similarity index 100% rename from internal/selfupdate/open_windows.go rename to internal/core/selfupdate/open_windows.go diff --git a/internal/selfupdate/probation.go b/internal/core/selfupdate/probation.go similarity index 100% rename from internal/selfupdate/probation.go rename to internal/core/selfupdate/probation.go diff --git a/internal/agentupdate/agentupdate.go b/internal/core/selfupdate/report.go similarity index 88% rename from internal/agentupdate/agentupdate.go rename to internal/core/selfupdate/report.go index ccfeeda..dc420c8 100644 --- a/internal/agentupdate/agentupdate.go +++ b/internal/core/selfupdate/report.go @@ -1,4 +1,4 @@ -// Package agentupdate tells the people at a board how an agent self-update +// The daemon side of an agent update: telling the people at the board how it // went (docs/architecture.md, section 12). // // An agent update spans two processes. The running agent stages the package, @@ -18,7 +18,8 @@ // Each outcome is shown once (state.json's agentUpdateSeen). When the batch // had more behind the agent (queued in the inbox for the new agent), the // screen is held until that finishes, so there is one screen, not two. -package agentupdate + +package selfupdate import ( "context" @@ -31,22 +32,21 @@ import ( "strings" "time" - "github.com/LensBridge/agent/internal/fsutil" - "github.com/LensBridge/agent/internal/notice" - "github.com/LensBridge/agent/internal/selfupdate" - "github.com/LensBridge/agent/internal/state" - "github.com/LensBridge/agent/internal/store" + "github.com/LensBridge/agent/internal/core/fsutil" + "github.com/LensBridge/agent/internal/core/notice" + "github.com/LensBridge/agent/internal/core/state" + "github.com/LensBridge/agent/internal/core/store" ) -// Screen is the update screen (package updatescreen). +// Screen is the update screen (kiosk.Screen). type Screen interface { OnScreen(ctx context.Context) bool Finish(ctx context.Context, n notice.Notice) Hold(ctx context.Context, n notice.Notice) } -// Deps is what a Reporter needs. -type Deps struct { +// ReporterDeps is what a Reporter needs. +type ReporterDeps struct { Layout store.Layout Version string // this agent's Screen Screen @@ -60,13 +60,13 @@ type Deps struct { // Reporter shows agent update outcomes. type Reporter struct { - d Deps + d ReporterDeps // watchTimeout bounds how long Watch waits for the root updater. watchTimeout, watchPoll time.Duration } -// New returns a Reporter. -func New(d Deps) *Reporter { +// NewReporter returns a Reporter. +func NewReporter(d ReporterDeps) *Reporter { if d.Logger == nil { d.Logger = slog.New(slog.DiscardHandler) } @@ -77,7 +77,7 @@ func New(d Deps) *Reporter { } // LastOutcome is the root updater's last outcome, if any. -func (r *Reporter) LastOutcome() *selfupdate.Outcome { return selfupdate.ReadOutcome(r.d.Layout) } +func (r *Reporter) LastOutcome() *Outcome { return ReadOutcome(r.d.Layout) } // Staged is called after a batch staged an agent (importer.Deps.AgentStaged): // it leaves the batch's outcome for the next agent, and watches for the @@ -96,7 +96,7 @@ func (r *Reporter) Staged(n notice.Notice) { func (r *Reporter) watch(ctx context.Context, since time.Time) { deadline := time.Now().Add(r.watchTimeout) for time.Now().Before(deadline) { - if o := r.LastOutcome(); o != nil && o.Status == selfupdate.StatusRefused && !before(o.At, since) { + if o := r.LastOutcome(); o != nil && o.Status == StatusRefused && !before(o.At, since) { r.markSeen(o.At) r.conclude(ctx, r.failure(*o, r.takePending())) r.d.Resume() @@ -128,7 +128,7 @@ func (r *Reporter) Startup(ctx context.Context) { var n notice.Notice switch { - case unseen && o.Status != selfupdate.StatusOK: + case unseen && o.Status != StatusOK: n = r.failure(*o, pending) case pending != nil: n = *pending @@ -159,10 +159,10 @@ func (r *Reporter) conclude(ctx context.Context, n notice.Notice) { // failure is the notice for an update that did not replace the agent. The // lines from its batch that are not about the agent still stand. -func (r *Reporter) failure(o selfupdate.Outcome, pending *notice.Notice) notice.Notice { +func (r *Reporter) failure(o Outcome, pending *notice.Notice) notice.Notice { var line string switch { - case o.Status == selfupdate.StatusRolledBack && o.To != "": + case o.Status == StatusRolledBack && o.To != "": line = "Agent " + o.To + " did not start correctly, so the board went back to " + o.From case o.To != "": line = "Agent " + o.To + " could not be installed on this board" diff --git a/internal/agentupdate/agentupdate_test.go b/internal/core/selfupdate/report_test.go similarity index 84% rename from internal/agentupdate/agentupdate_test.go rename to internal/core/selfupdate/report_test.go index 09bb46c..84c7d3a 100644 --- a/internal/agentupdate/agentupdate_test.go +++ b/internal/core/selfupdate/report_test.go @@ -1,4 +1,4 @@ -package agentupdate +package selfupdate import ( "context" @@ -9,9 +9,8 @@ import ( "testing" "time" - "github.com/LensBridge/agent/internal/notice" - "github.com/LensBridge/agent/internal/selfupdate" - "github.com/LensBridge/agent/internal/store" + "github.com/LensBridge/agent/internal/core/notice" + "github.com/LensBridge/agent/internal/core/store" ) type fakeScreen struct { @@ -38,7 +37,7 @@ func newEnv(t *testing.T, version string) *env { t.Helper() e := &env{l: store.Layout{Root: t.TempDir()}, screen: &fakeScreen{}} os.MkdirAll(filepath.Join(e.l.Root, "agent"), 0o750) - e.r = New(Deps{ + e.r = NewReporter(ReporterDeps{ Layout: e.l, Version: version, Screen: e.screen, Banner: func(n notice.Notice) { e.banners = append(e.banners, n) }, Resume: func() { e.resumed++ }, @@ -47,7 +46,7 @@ func newEnv(t *testing.T, version string) *env { return e } -func (e *env) outcome(t *testing.T, o selfupdate.Outcome) { +func (e *env) outcome(t *testing.T, o Outcome) { t.Helper() raw, _ := json.Marshal(o) if err := os.WriteFile(e.l.AgentLastUpdate(), raw, 0o644); err != nil { @@ -85,8 +84,8 @@ func TestRollbackIsShownOnce(t *testing.T) { e := newEnv(t, "0.2.1") e.screen.onScreen = true staged(t, e) - e.outcome(t, selfupdate.Outcome{From: "0.2.1", To: "0.3.0", At: "2026-09-25T23:01:00Z", - Status: selfupdate.StatusRolledBack, Message: "agent 0.3.0 did not come up healthy"}) + e.outcome(t, Outcome{From: "0.2.1", To: "0.3.0", At: "2026-09-25T23:01:00Z", + Status: StatusRolledBack, Message: "agent 0.3.0 did not come up healthy"}) e.r.Startup(context.Background()) if len(e.screen.finished) != 1 { t.Fatalf("finished = %+v", e.screen.finished) @@ -107,7 +106,7 @@ func TestRollbackIsShownOnce(t *testing.T) { func TestRollbackOffScreenIsABanner(t *testing.T) { e := newEnv(t, "0.2.1") - e.outcome(t, selfupdate.Outcome{From: "0.2.1", To: "0.3.0", At: "2026-09-25T23:01:00Z", Status: selfupdate.StatusRolledBack}) + e.outcome(t, Outcome{From: "0.2.1", To: "0.3.0", At: "2026-09-25T23:01:00Z", Status: StatusRolledBack}) e.r.Startup(context.Background()) if len(e.banners) != 1 || e.banners[0].Tone != notice.Problem || len(e.screen.finished) != 0 { t.Fatalf("banners %+v, finished %+v", e.banners, e.screen.finished) @@ -128,7 +127,7 @@ func TestQueuedBatchHoldsTheScreen(t *testing.T) { func TestPlainStartupSaysNothing(t *testing.T) { e := newEnv(t, "0.3.0") - e.outcome(t, selfupdate.Outcome{From: "0.2.1", To: "0.3.0", At: "2026-09-25T23:01:00Z", Status: selfupdate.StatusOK}) + e.outcome(t, Outcome{From: "0.2.1", To: "0.3.0", At: "2026-09-25T23:01:00Z", Status: StatusOK}) e.r.Startup(context.Background()) if len(e.banners)+len(e.screen.finished)+len(e.screen.held) != 0 { t.Fatal("a successful update from long ago was announced") @@ -143,8 +142,8 @@ func TestRefusalIsNoticed(t *testing.T) { e.r.d.Resume = func() { close(resumed) } // The outcome is in place before the watch starts, so the watch's reads // and this write do not overlap. - e.outcome(t, selfupdate.Outcome{From: "0.2.1", To: "0.3.0", At: "2026-09-25T23:00:03Z", - Status: selfupdate.StatusRefused, Message: "the staged package did not verify"}) + e.outcome(t, Outcome{From: "0.2.1", To: "0.3.0", At: "2026-09-25T23:00:03Z", + Status: StatusRefused, Message: "the staged package did not verify"}) e.r.Staged(notice.New(notice.OK, "Update complete", "Agent 0.3.0", "Board app 2.1.0")) select { case <-resumed: diff --git a/internal/selfupdate/selfupdate.go b/internal/core/selfupdate/selfupdate.go similarity index 97% rename from internal/selfupdate/selfupdate.go rename to internal/core/selfupdate/selfupdate.go index 0fdea0c..8dce98e 100644 --- a/internal/selfupdate/selfupdate.go +++ b/internal/core/selfupdate/selfupdate.go @@ -33,11 +33,11 @@ import ( "strings" "time" - "github.com/LensBridge/agent/internal/fsutil" - "github.com/LensBridge/agent/internal/mbu" - "github.com/LensBridge/agent/internal/state" - "github.com/LensBridge/agent/internal/store" - "github.com/LensBridge/agent/internal/trust" + "github.com/LensBridge/agent/internal/core/fsutil" + "github.com/LensBridge/agent/internal/core/mbu" + "github.com/LensBridge/agent/internal/core/state" + "github.com/LensBridge/agent/internal/core/store" + "github.com/LensBridge/agent/internal/core/trust" ) // Production paths and names. @@ -435,11 +435,6 @@ func (u *Updater) commit(ctx context.Context, rec *Txn) (Outcome, error) { Message: fmt.Sprintf("Updated the agent from %s to %s", rec.From, rec.To)} err := u.finish(&out) u.crashpoint("committed") - // The enrollment splash ships inside the binary; bring it up to date with - // it. Best effort: the splash is only seen before enrollment. - if o, err := u.Run(context.WithoutCancel(ctx), u.Binary, "splash", "install"); err != nil { - u.Logf("could not refresh the enrollment splash: %v %s", err, firstLine(o)) - } if rerr := removeDurable(u.Txn); rerr != nil { u.Logf("could not remove %s: %v", u.Txn, rerr) } diff --git a/internal/selfupdate/selfupdate_test.go b/internal/core/selfupdate/selfupdate_test.go similarity index 98% rename from internal/selfupdate/selfupdate_test.go rename to internal/core/selfupdate/selfupdate_test.go index 8cf8a54..a873730 100644 --- a/internal/selfupdate/selfupdate_test.go +++ b/internal/core/selfupdate/selfupdate_test.go @@ -16,10 +16,10 @@ import ( "testing" "time" - "github.com/LensBridge/agent/internal/mbu" - "github.com/LensBridge/agent/internal/state" - "github.com/LensBridge/agent/internal/store" - "github.com/LensBridge/agent/internal/trust" + "github.com/LensBridge/agent/internal/core/mbu" + "github.com/LensBridge/agent/internal/core/state" + "github.com/LensBridge/agent/internal/core/store" + "github.com/LensBridge/agent/internal/core/trust" ) var ( @@ -261,7 +261,7 @@ func TestApplyOK(t *testing.T) { if took := h.now.Sub(start); took < ProbationPeriod { t.Errorf("committed after %s, before the probation was over", took) } - if h.count("systemctl restart "+AgentUnit) != 1 || h.count("musallahboard-agent splash install") != 1 { + if h.count("systemctl restart "+AgentUnit) != 1 { t.Errorf("commands = %q", h.cmds) } if h.cmds[0] != ".musallahboard-agent.new version" { @@ -606,7 +606,7 @@ func TestOutcomeOfAResumedCommitIsTheSame(t *testing.T) { if _, err := u.Apply(context.Background()); err != nil { t.Fatal(err) } - // agentupdate shows an outcome once, by its timestamp. + // The Reporter shows an outcome once, by its timestamp. if again := lastUpdate(t, u); again != first { t.Errorf("outcome rewritten: %+v, was %+v", again, first) } diff --git a/internal/selfupdate/txn.go b/internal/core/selfupdate/txn.go similarity index 99% rename from internal/selfupdate/txn.go rename to internal/core/selfupdate/txn.go index d39c542..0898fed 100644 --- a/internal/selfupdate/txn.go +++ b/internal/core/selfupdate/txn.go @@ -12,7 +12,7 @@ import ( "path/filepath" "slices" - "github.com/LensBridge/agent/internal/fsutil" + "github.com/LensBridge/agent/internal/core/fsutil" ) // The update transaction (docs/architecture.md, section 12). diff --git a/internal/state/lock_unix.go b/internal/core/state/lock_unix.go similarity index 100% rename from internal/state/lock_unix.go rename to internal/core/state/lock_unix.go diff --git a/internal/state/lock_windows.go b/internal/core/state/lock_windows.go similarity index 100% rename from internal/state/lock_windows.go rename to internal/core/state/lock_windows.go diff --git a/internal/state/state.go b/internal/core/state/state.go similarity index 98% rename from internal/state/state.go rename to internal/core/state/state.go index 187a086..101aa72 100644 --- a/internal/state/state.go +++ b/internal/core/state/state.go @@ -17,7 +17,7 @@ import ( "path/filepath" "slices" - "github.com/LensBridge/agent/internal/fsutil" + "github.com/LensBridge/agent/internal/core/fsutil" ) // State is state.json. diff --git a/internal/state/state_test.go b/internal/core/state/state_test.go similarity index 100% rename from internal/state/state_test.go rename to internal/core/state/state_test.go diff --git a/internal/store/app.go b/internal/core/store/app.go similarity index 97% rename from internal/store/app.go rename to internal/core/store/app.go index f1c2241..0015a82 100644 --- a/internal/store/app.go +++ b/internal/core/store/app.go @@ -8,8 +8,8 @@ import ( "path/filepath" "time" - "github.com/LensBridge/agent/internal/fsutil" - "github.com/LensBridge/agent/internal/mbu" + "github.com/LensBridge/agent/internal/core/fsutil" + "github.com/LensBridge/agent/internal/core/mbu" ) // App is an installed board app release. diff --git a/internal/store/content.go b/internal/core/store/content.go similarity index 99% rename from internal/store/content.go rename to internal/core/store/content.go index d5fdf36..9f57b23 100644 --- a/internal/store/content.go +++ b/internal/core/store/content.go @@ -16,8 +16,8 @@ import ( "sync" "time" - "github.com/LensBridge/agent/internal/fsutil" - "github.com/LensBridge/agent/internal/mbu" + "github.com/LensBridge/agent/internal/core/fsutil" + "github.com/LensBridge/agent/internal/core/mbu" ) // Content is an installed content bundle. diff --git a/internal/store/day.go b/internal/core/store/day.go similarity index 96% rename from internal/store/day.go rename to internal/core/store/day.go index 4ec46e0..e6ccbfa 100644 --- a/internal/store/day.go +++ b/internal/core/store/day.go @@ -3,7 +3,7 @@ package store import ( "time" - "github.com/LensBridge/agent/internal/mbu" + "github.com/LensBridge/agent/internal/core/mbu" ) // Day is the answer to "which payload should the board show right now". diff --git a/internal/store/layout.go b/internal/core/store/layout.go similarity index 96% rename from internal/store/layout.go rename to internal/core/store/layout.go index 6a1a01e..bcaf22e 100644 --- a/internal/store/layout.go +++ b/internal/core/store/layout.go @@ -12,7 +12,7 @@ import ( "errors" "path/filepath" - "github.com/LensBridge/agent/internal/state" + "github.com/LensBridge/agent/internal/core/state" ) // DefaultRoot is the daemon's StateDirectory. @@ -43,7 +43,7 @@ func (l Layout) AgentStagedDir() string { return filepath.Join(l.Root, "agent", func (l Layout) AgentLastUpdate() string { return filepath.Join(l.Root, "agent", "last-update.json") } // AgentPendingNotice is the outcome of the batch that staged an agent, left -// for the agent that starts next to show (package agentupdate). +// for the agent that starts next to show (selfupdate.Reporter). func (l Layout) AgentPendingNotice() string { return filepath.Join(l.Root, "agent", "pending-notice.json") } diff --git a/internal/trust/owner_unix.go b/internal/core/trust/owner_unix.go similarity index 93% rename from internal/trust/owner_unix.go rename to internal/core/trust/owner_unix.go index c58b926..2608314 100644 --- a/internal/trust/owner_unix.go +++ b/internal/core/trust/owner_unix.go @@ -11,7 +11,7 @@ import ( ) // checkRootOwned refuses a trust store the daemon could have planted. -// /etc/musallahboard is writable by the daemon (it writes kiosk-url), so it +// /etc/musallahboard is writable by the daemon (it writes agent.toml), so it // could unlink trust.json and put its own file there; that file would be // owned by the daemon, not root. Hard links to someone else's file are // caught by the link count. Run unprivileged (tests, a dev box) there is no diff --git a/internal/trust/owner_windows.go b/internal/core/trust/owner_windows.go similarity index 100% rename from internal/trust/owner_windows.go rename to internal/core/trust/owner_windows.go diff --git a/internal/trust/trust.go b/internal/core/trust/trust.go similarity index 98% rename from internal/trust/trust.go rename to internal/core/trust/trust.go index 011e1b9..233172b 100644 --- a/internal/trust/trust.go +++ b/internal/core/trust/trust.go @@ -24,7 +24,7 @@ import ( "os" "strings" - "github.com/LensBridge/agent/internal/fsutil" + "github.com/LensBridge/agent/internal/core/fsutil" ) // DefaultPath is the trust store on a board. @@ -33,7 +33,7 @@ const DefaultPath = "/etc/musallahboard/trust.json" // BuiltinReleaseKeys is a comma-separated list of base64 release public keys, // set at build time: // -// -ldflags "-X github.com/LensBridge/agent/internal/trust.BuiltinReleaseKeys=[,]" +// -ldflags "-X github.com/LensBridge/agent/internal/core/trust.BuiltinReleaseKeys=[,]" // // A build without it (a developer build) accepts only release keys listed in // trust.json. diff --git a/internal/trust/trust_test.go b/internal/core/trust/trust_test.go similarity index 100% rename from internal/trust/trust_test.go rename to internal/core/trust/trust_test.go diff --git a/internal/boardsync/channel.go b/internal/core/updates/channel.go similarity index 64% rename from internal/boardsync/channel.go rename to internal/core/updates/channel.go index 66e06e9..53bbcd2 100644 --- a/internal/boardsync/channel.go +++ b/internal/core/updates/channel.go @@ -1,4 +1,4 @@ -package boardsync +package updates import ( "context" @@ -7,15 +7,36 @@ import ( "encoding/json" "errors" "fmt" + "hash" "io" + "math/rand" "net/http" "net/url" + "os" "path/filepath" "regexp" - "runtime" "strings" + "time" - "github.com/LensBridge/agent/internal/mbu" + "github.com/LensBridge/agent/internal/core/mbu" +) + +// Release channel timings (docs/architecture.md, section 9.4). They are +// fields on the Scheduler (set from these in New) so tests can shrink them. +const ( + ChannelFirstDelay = 2 * time.Minute + ChannelInterval = 6 * time.Hour + // ChannelRetry is the first retry after a failed channel check. It + // doubles on each failure, up to ChannelInterval. + ChannelRetry = 5 * time.Minute + // ChannelTimeout bounds one fetch of a channel file, which is a few + // hundred bytes: a request that has had no answer by then is stuck. + ChannelTimeout = 30 * time.Second + + // maxChannelBytes bounds a channel pointer file. + maxChannelBytes = 1 << 20 + // maxPackage is the largest package the board will download. + maxPackage = mbu.MaxPackageBytes ) // Channel is a release channel pointer file (section 9.4). It is only a @@ -31,7 +52,10 @@ type Channel struct { var sha256HexRE = regexp.MustCompile(`^[0-9a-f]{64}$`) -func (s *Syncer) channelLoop(ctx context.Context) { +// channelLoop checks the release channels on schedule until ctx ends. Nothing +// here needs the board to be enrolled: the channels are public files, and +// what they point at is verified against the release keys like any package. +func (s *Scheduler) channelLoop(ctx context.Context) { if !sleep(ctx, s.channelFirstDelay) { return } @@ -41,7 +65,7 @@ func (s *Syncer) channelLoop(ctx context.Context) { if ctx.Err() != nil { return } - s.d.Updates.CheckDone(err) + s.CheckDone(err) wait := s.channelInterval if err != nil { // A failed check is usually the network: try again soon rather @@ -62,14 +86,14 @@ func (s *Syncer) channelLoop(ctx context.Context) { // quiet window. The agent goes first because an app release may need a newer // local API than the running agent serves: the scheduler only holds such an // app when a new enough agent is waiting with it. -func (s *Syncer) CheckChannels(ctx context.Context) error { +func (s *Scheduler) CheckChannels(ctx context.Context) error { var errs []error - if u := s.d.Cfg.AgentChannelURL(runtime.GOARCH); u != "" { + if u := s.d.AgentChannel; u != "" { if err := s.checkChannel(ctx, mbu.TypeAgent, u); err != nil { errs = append(errs, fmt.Errorf("agent channel: %w", err)) } } - if u := s.d.Cfg.AppChannelURL(); u != "" { + if u := s.d.AppChannel; u != "" { if err := s.checkChannel(ctx, mbu.TypeApp, u); err != nil { errs = append(errs, fmt.Errorf("app channel: %w", err)) } @@ -79,8 +103,8 @@ func (s *Syncer) CheckChannels(ctx context.Context) error { // checkChannel fetches one channel and, if it points at something newer than // what is installed or already waiting, downloads it and offers it to the -// update scheduler. -func (s *Syncer) checkChannel(ctx context.Context, kind mbu.Type, channelURL string) error { +// scheduler. +func (s *Scheduler) checkChannel(ctx context.Context, kind mbu.Type, channelURL string) error { ch, err := s.fetchChannel(ctx, channelURL) if err != nil { return err @@ -116,7 +140,7 @@ func (s *Syncer) checkChannel(ctx context.Context, kind mbu.Type, channelURL str s.log.Debug("release channel: up to date", "type", kind, "installed", installed, "channel", ch.Version) return nil } - if waiting := s.d.Updates.Pending(kind); waiting != "" && mbu.CompareVersions(ch.Version, waiting) <= 0 { + if waiting := s.Pending(kind); waiting != "" && mbu.CompareVersions(ch.Version, waiting) <= 0 { s.log.Debug("release channel: already waiting to install", "type", kind, "version", waiting) return nil } @@ -135,10 +159,10 @@ func (s *Syncer) checkChannel(ctx context.Context, kind mbu.Type, channelURL str if err := s.download(ctx, pkgURL, file, ch); err != nil { return err } - return s.d.Updates.Offer(file) + return s.Offer(file) } -func (s *Syncer) fetchChannel(ctx context.Context, channelURL string) (*Channel, error) { +func (s *Scheduler) fetchChannel(ctx context.Context, channelURL string) (*Channel, error) { raw, err := s.fetchChannelFile(ctx, channelURL) if err != nil && ctx.Err() == nil && !errors.As(err, new(statusError)) { // No answer at all: the pooled connection may be dead. Drop it and @@ -177,7 +201,7 @@ type statusError int func (e statusError) Error() string { return fmt.Sprintf("channel returned %d", int(e)) } // fetchChannelFile makes one bounded attempt at a channel file. -func (s *Syncer) fetchChannelFile(ctx context.Context, channelURL string) ([]byte, error) { +func (s *Scheduler) fetchChannelFile(ctx context.Context, channelURL string) ([]byte, error) { ctx, cancel := context.WithTimeout(ctx, s.channelTimeout) defer cancel() req, err := http.NewRequestWithContext(ctx, http.MethodGet, channelURL, nil) @@ -198,7 +222,7 @@ func (s *Syncer) fetchChannelFile(ctx context.Context, channelURL string) ([]byt // download fetches the package and checks its size and hash against the // channel before anything else looks at it. -func (s *Syncer) download(ctx context.Context, pkgURL, file string, ch *Channel) error { +func (s *Scheduler) download(ctx context.Context, pkgURL, file string, ch *Channel) error { req, err := http.NewRequestWithContext(ctx, http.MethodGet, pkgURL, nil) if err != nil { return err @@ -246,3 +270,77 @@ func resolve(base, ref string) (string, error) { } return u.String(), nil } + +func (s *Scheduler) do(req *http.Request) (*http.Response, error) { + req.Header.Set("User-Agent", "musallahboard-agent/"+s.d.AgentVersion) + return s.client.Do(req) +} + +// downloadPrefix names the hidden inbox directories downloads are made in. +// The inbox runner ignores hidden entries, so a half-written package is never +// picked up, and they are on the same filesystem as the updates directory. +const downloadPrefix = ".channel-" + +func (s *Scheduler) downloadDir() (string, error) { + inbox := s.d.Layout.Inbox() + if err := os.MkdirAll(inbox, 0o770); err != nil { + return "", err + } + return os.MkdirTemp(inbox, downloadPrefix) +} + +// cleanStaleDownloads removes download directories a previous run left +// behind when it was killed mid-download. +func (s *Scheduler) cleanStaleDownloads() { + matches, _ := filepath.Glob(filepath.Join(s.d.Layout.Inbox(), downloadPrefix+"*")) + for _, m := range matches { + os.RemoveAll(m) + } +} + +var errTooLarge = fmt.Errorf("the download is larger than %d MiB, the most a package may be", maxPackage>>20) + +// saveCapped streams r into a new file at path, reading at most limit bytes; +// anything longer is errTooLarge and the file is removed. Every byte is also +// hashed into h. +func saveCapped(path string, r io.Reader, limit int64, h hash.Hash) (int64, error) { + f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o640) + if err != nil { + return 0, err + } + // One byte past the limit tells "exactly at the limit" from "too big". + n, err := io.Copy(io.MultiWriter(f, h), io.LimitReader(r, limit+1)) + if err == nil && n > limit { + err = errTooLarge + } + if err == nil { + err = f.Sync() + } + if cerr := f.Close(); err == nil { + err = cerr + } + if err != nil { + os.Remove(path) + } + return n, err +} + +func sleep(ctx context.Context, d time.Duration) bool { + t := time.NewTimer(d) + defer t.Stop() + select { + case <-ctx.Done(): + return false + case <-t.C: + return true + } +} + +func jitter(b time.Duration) time.Duration { + if b < 4 { + return 0 + } + return time.Duration(rand.Int63n(int64(b / 4))) +} + +func removeAll(p string) { _ = os.RemoveAll(p) } diff --git a/internal/core/updates/channel_test.go b/internal/core/updates/channel_test.go new file mode 100644 index 0000000..6962dee --- /dev/null +++ b/internal/core/updates/channel_test.go @@ -0,0 +1,269 @@ +package updates + +import ( + "bytes" + "context" + "crypto/ed25519" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "net/http" + "net/http/httptest" + "os" + "runtime" + "strings" + "sync/atomic" + "testing" + "time" + + "github.com/LensBridge/agent/internal/core/mbu" + "github.com/LensBridge/agent/internal/core/state" +) + +func hexSHA(b []byte) string { + h := sha256.Sum256(b) + return hex.EncodeToString(h[:]) +} + +func packageBytes(t *testing.T, m mbu.Manifest, src []mbu.Source) []byte { + t.Helper() + var buf bytes.Buffer + if err := mbu.Build(&buf, m, src, []ed25519.PrivateKey{releaseKey}); err != nil { + t.Fatalf("Build: %v", err) + } + return buf.Bytes() +} + +func appPackageBytes(t *testing.T, version string) []byte { + return packageBytes(t, mbu.Manifest{Type: mbu.TypeApp, Version: version, App: &mbu.AppInfo{LocalAPI: 2}}, + []mbu.Source{{Path: "index.html", Data: []byte("" + version)}}) +} + +func agentPackageBytes(t *testing.T, version string) []byte { + return packageBytes(t, mbu.Manifest{Type: mbu.TypeAgent, Version: version, + Agent: &mbu.AgentInfo{Arch: runtime.GOARCH, Binary: "musallahboard-agent"}}, + []mbu.Source{{Path: "musallahboard-agent", Data: []byte("#!/bin/sh\necho " + version)}}) +} + +// channelServer serves a channel file at /channel.json and the package at +// /pkg.mbu, counting package downloads. +type channelServer struct { + *httptest.Server + downloads atomic.Int32 + channel Channel + pkg []byte +} + +func newChannelServer(t *testing.T, version string, pkg []byte) *channelServer { + cs := &channelServer{pkg: pkg} + cs.channel = Channel{Version: version, URL: "pkg.mbu", SHA256: hexSHA(pkg), Bytes: int64(len(pkg))} + cs.Server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + switch r.URL.Path { + case "/channel.json": + json.NewEncoder(w).Encode(cs.channel) + case "/pkg.mbu": + cs.downloads.Add(1) + w.Write(cs.pkg) + default: + http.NotFound(w, r) + } + })) + t.Cleanup(cs.Close) + return cs +} + +func TestAppChannel(t *testing.T) { + cases := []struct { + name string + installed string + channel string + downloads int32 + waiting string + }{ + {"newer waits", "2.0.0", "2.1.0", 1, "2.1.0"}, + {"nothing installed waits (and installs at once)", "", "2.1.0", 1, "2.1.0"}, + {"equal skips", "2.1.0", "2.1.0", 0, ""}, + {"older skips", "2.2.0", "2.1.0", 0, ""}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + cs := newChannelServer(t, tc.channel, appPackageBytes(t, tc.channel)) + e := newEnv(t) + e.s = e.newScheduler(func(d *Deps) { d.AppChannel = cs.URL + "/channel.json" }) + setApp(t, e.l, tc.installed) + if err := e.s.CheckChannels(context.Background()); err != nil { + t.Fatal(err) + } + if n := cs.downloads.Load(); n != tc.downloads { + t.Errorf("downloads = %d, want %d", n, tc.downloads) + } + if got := e.s.Pending(mbu.TypeApp); got != tc.waiting { + t.Errorf("waiting = %q, want %q", got, tc.waiting) + } + st, _ := e.l.State().Load() + if st.AppVersion != tc.installed { + t.Errorf("app version = %q: the channel check installed it", st.AppVersion) + } + // A second check does not download what is already waiting. + if err := e.s.CheckChannels(context.Background()); err != nil { + t.Fatal(err) + } + if n := cs.downloads.Load(); n != tc.downloads { + t.Errorf("downloads after a second check = %d, want %d", n, tc.downloads) + } + }) + } +} + +func TestAppChannelShaMismatch(t *testing.T) { + cs := newChannelServer(t, "2.1.0", appPackageBytes(t, "2.1.0")) + cs.channel.SHA256 = strings.Repeat("0", 64) + e := newEnv(t) + err := e.s.checkChannel(context.Background(), mbu.TypeApp, cs.URL+"/channel.json") + if err == nil || !strings.Contains(err.Error(), "SHA-256") { + t.Fatalf("err = %v", err) + } + if st, _ := e.l.State().Load(); st.AppVersion != "2.0.0" { + t.Fatalf("installed %q despite the hash mismatch", st.AppVersion) + } +} + +func TestAppChannelSizeMismatch(t *testing.T) { + cs := newChannelServer(t, "2.1.0", appPackageBytes(t, "2.1.0")) + cs.channel.Bytes -= 10 + e := newEnv(t) + err := e.s.checkChannel(context.Background(), mbu.TypeApp, cs.URL+"/channel.json") + if err == nil || !strings.Contains(err.Error(), "larger than") { + t.Fatalf("err = %v", err) + } +} + +func TestChannelValidation(t *testing.T) { + cs := newChannelServer(t, "2.1", appPackageBytes(t, "2.1.0")) + e := newEnv(t) + err := e.s.checkChannel(context.Background(), mbu.TypeApp, cs.URL+"/channel.json") + if err == nil || !strings.Contains(err.Error(), "MAJOR.MINOR.PATCH") { + t.Fatalf("err = %v", err) + } +} + +func TestAgentChannel(t *testing.T) { + cases := []struct { + name string + running string + channel string + rejected []string + downloads int32 + waiting string + }{ + {"newer waits", "0.3.0", "0.4.0", nil, 1, "0.4.0"}, + {"equal skips", "0.3.0", "0.3.0", nil, 0, ""}, + {"older skips", "0.3.0", "0.2.9", nil, 0, ""}, + {"rejected skips", "0.3.0", "0.4.0", []string{"0.4.0"}, 0, ""}, + {"dev build skips", "dev", "0.4.0", nil, 0, ""}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + cs := newChannelServer(t, tc.channel, agentPackageBytes(t, tc.channel)) + e := newEnv(t) + e.s = e.newScheduler(func(d *Deps) { d.AgentChannel = cs.URL + "/channel.json"; d.AgentVersion = tc.running }) + if tc.rejected != nil { + e.l.State().Update(func(s *state.State) error { s.AgentVersionsRejected = tc.rejected; return nil }) + } + e.s.CheckChannels(context.Background()) + if n := cs.downloads.Load(); n != tc.downloads { + t.Errorf("downloads = %d, want %d", n, tc.downloads) + } + if got := e.s.Pending(mbu.TypeAgent); got != tc.waiting { + t.Errorf("waiting = %q, want %q", got, tc.waiting) + } + if _, err := os.Stat(e.l.StagedReady()); err == nil { + t.Error("the channel check staged the agent instead of leaving it waiting") + } + }) + } +} + +func TestAutoUpdateOffSkipsChannels(t *testing.T) { + cs := newChannelServer(t, "2.1.0", appPackageBytes(t, "2.1.0")) + e := newEnv(t) + e.s = e.newScheduler(func(d *Deps) { d.AppChannel = cs.URL + "/channel.json"; d.AutoUpdate = false }) + e.s.channelFirstDelay = time.Millisecond + ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond) + defer cancel() + e.s.Run(ctx) + if cs.downloads.Load() != 0 { + t.Fatal("channel followed with auto_update off") + } +} + +// A channel request that gets no answer (a dead pooled connection, a board +// that just lost its network) is given up on and retried once on a new +// connection, instead of waiting minutes for response headers. +func TestChannelFetchRetriesAStuckRequest(t *testing.T) { + cs := newChannelServer(t, "2.1.0", appPackageBytes(t, "2.1.0")) + release := make(chan struct{}) + var calls atomic.Int32 + stuck := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if calls.Add(1) == 1 { + select { + case <-release: + case <-r.Context().Done(): + } + return + } + http.Redirect(w, r, cs.URL+"/channel.json", http.StatusFound) + })) + defer stuck.Close() + defer close(release) + + e := newEnv(t) + e.s.channelTimeout = 200 * time.Millisecond + ch, err := e.s.fetchChannel(context.Background(), stuck.URL+"/channel.json") + if err != nil { + t.Fatal(err) + } + if ch.Version != "2.1.0" || calls.Load() != 2 { + t.Fatalf("version %q after %d calls", ch.Version, calls.Load()) + } +} + +// A server that answers is not asked twice. +func TestChannelFetchDoesNotRetryAnAnswer(t *testing.T) { + var calls atomic.Int32 + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + calls.Add(1) + http.NotFound(w, r) + })) + defer srv.Close() + e := newEnv(t) + if _, err := e.s.fetchChannel(context.Background(), srv.URL+"/channel.json"); err == nil || calls.Load() != 1 { + t.Fatalf("err %v after %d calls", err, calls.Load()) + } +} + +// A failed check is retried soon, not after the full channel interval. +func TestFailedChannelCheckRetriesSoon(t *testing.T) { + var calls atomic.Int32 + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + calls.Add(1) + http.Error(w, "down", http.StatusBadGateway) + })) + defer srv.Close() + e := newEnv(t) + e.s = e.newScheduler(func(d *Deps) { d.AppChannel = srv.URL + "/channel.json"; d.AutoUpdate = true }) + e.s.channelFirstDelay = time.Millisecond + e.s.channelRetry = 10 * time.Millisecond + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + go e.s.Run(ctx) + for calls.Load() < 3 { + if ctx.Err() != nil { + t.Fatalf("%d checks in 5s; a failure waited the full interval", calls.Load()) + } + time.Sleep(5 * time.Millisecond) + } + if e.s.Info().LastCheckError == "" { + t.Fatal("the failure was not reported") + } +} diff --git a/internal/updates/updates.go b/internal/core/updates/updates.go similarity index 84% rename from internal/updates/updates.go rename to internal/core/updates/updates.go index a118b04..cbbd334 100644 --- a/internal/updates/updates.go +++ b/internal/core/updates/updates.go @@ -1,6 +1,8 @@ -// Package updates holds board software (the app and the agent) that the -// release channels found, and installs it in the board's quiet window rather -// than the moment it arrives (docs/architecture.md, section 9.4). While +// Package updates follows the release channels for board software (the app +// and the agent), holds what they offer, and installs it in the board's quiet +// window rather than the moment it arrives (docs/architecture.md, section +// 9.4). The channels are public files on GitHub: a board needs a network to +// follow them, but not enrollment or a device key. While // something waits, /api/local/status says what and when, and the board app // puts it on the ticker. // @@ -17,15 +19,17 @@ import ( "fmt" "io/fs" "log/slog" + "net/http" "os" "path/filepath" "sync" "time" - "github.com/LensBridge/agent/internal/fsutil" - "github.com/LensBridge/agent/internal/importer" - "github.com/LensBridge/agent/internal/mbu" - "github.com/LensBridge/agent/internal/store" + "github.com/LensBridge/agent/internal/core/fsutil" + "github.com/LensBridge/agent/internal/core/importer" + "github.com/LensBridge/agent/internal/core/mbu" + "github.com/LensBridge/agent/internal/core/netinfo" + "github.com/LensBridge/agent/internal/core/store" ) // Window is how long after the install time a waiting update still installs. @@ -84,14 +88,18 @@ type Outcome struct { type Deps struct { Layout store.Layout Importer *importer.Importer - // Check asks the release channels for new software, which they hand to - // Offer. Nil when the board cannot reach them (no device key). - Check func(ctx context.Context) error + // AppChannel and AgentChannel are the release channel URLs + // (agent.toml); "" disables that channel. + AppChannel, AgentChannel string + // AgentVersion is the running agent's. + AgentVersion string + // HTTP is optional; New uses netinfo.NewHTTPClient. + HTTP *http.Client // Changed is told whenever Info changes. May be nil. Changed func(Info) Hour, Minute int - // AutoUpdate is reported in Info; the scheduler itself holds and - // installs whatever it is offered either way. + // AutoUpdate is whether the channels are checked in the background + // (auto_update). `update now` checks them either way. AutoUpdate bool Logger *slog.Logger Now func() time.Time @@ -99,9 +107,13 @@ type Deps struct { // Scheduler holds waiting updates and installs them. type Scheduler struct { - d Deps - log *slog.Logger - kick chan struct{} + d Deps + log *slog.Logger + kick chan struct{} + client *http.Client + + channelFirstDelay, channelInterval time.Duration + channelRetry, channelTimeout time.Duration // installMu is held while packages move in or out of the updates // directory, so an Offer never replaces a file the importer is reading. @@ -122,11 +134,19 @@ func New(d Deps) *Scheduler { if d.Logger == nil { d.Logger = slog.New(slog.DiscardHandler) } + if d.HTTP == nil { + d.HTTP = netinfo.NewHTTPClient() + } s := &Scheduler{ - d: d, - log: d.Logger.With("component", "updates"), - kick: make(chan struct{}, 1), - pending: map[mbu.Type]*mbu.Manifest{}, + d: d, + log: d.Logger.With("component", "updates"), + kick: make(chan struct{}, 1), + client: d.HTTP, + pending: map[mbu.Type]*mbu.Manifest{}, + channelFirstDelay: ChannelFirstDelay, + channelInterval: ChannelInterval, + channelRetry: ChannelRetry, + channelTimeout: ChannelTimeout, } s.load() return s @@ -238,10 +258,17 @@ func (s *Scheduler) Info() Info { return info } -// Run installs waiting updates when their window opens, and serves the CLI's -// install-now requests, until ctx ends. +// Run follows the release channels (with auto_update), installs waiting +// updates when their window opens, and serves the CLI's install-now +// requests, until ctx ends. func (s *Scheduler) Run(ctx context.Context) { + s.cleanStaleDownloads() go s.watchRequests(ctx) + if s.d.AutoUpdate { + go s.channelLoop(ctx) + } else { + s.log.Info("release channels are off (auto_update = false)") + } t := time.NewTicker(checkInterval) defer t.Stop() for { @@ -274,14 +301,10 @@ func (s *Scheduler) CheckDone(err error) { // started always finishes, because stopping one halfway helps nobody. func (s *Scheduler) CheckAndInstall(ctx context.Context) Outcome { var out Outcome - if s.d.Check == nil { - out.CheckError = "this board cannot reach the release channels (no device key)" - } else { - err := s.d.Check(ctx) - s.CheckDone(err) - if err != nil { - out.CheckError = err.Error() - } + err := s.CheckChannels(ctx) + s.CheckDone(err) + if err != nil { + out.CheckError = err.Error() } b, _ := s.InstallNow(context.WithoutCancel(ctx)) out.Results = b.Results diff --git a/internal/updates/updates_test.go b/internal/core/updates/updates_test.go similarity index 84% rename from internal/updates/updates_test.go rename to internal/core/updates/updates_test.go index 7f593a2..230bb69 100644 --- a/internal/updates/updates_test.go +++ b/internal/core/updates/updates_test.go @@ -3,23 +3,30 @@ package updates import ( "bytes" "context" - "errors" "crypto/ed25519" + "net/http" + "net/http/httptest" "os" "path/filepath" "runtime" + "strings" "testing" "time" - "github.com/LensBridge/agent/internal/importer" - "github.com/LensBridge/agent/internal/mbu" - "github.com/LensBridge/agent/internal/state" - "github.com/LensBridge/agent/internal/store" - "github.com/LensBridge/agent/internal/trust" + "github.com/LensBridge/agent/internal/core/config" + "github.com/LensBridge/agent/internal/core/importer" + "github.com/LensBridge/agent/internal/core/mbu" + "github.com/LensBridge/agent/internal/core/state" + "github.com/LensBridge/agent/internal/core/store" + "github.com/LensBridge/agent/internal/core/trust" ) var releaseKey = ed25519.NewKeyFromSeed(bytes.Repeat([]byte{2}, 32)) +// The install window is in the system zone when there is no content; the +// tests pin it to UTC once, before any test server reads the clock. +func init() { time.Local = time.UTC } + type env struct { l store.Layout im *importer.Importer @@ -33,11 +40,10 @@ type env struct { // is the system's; tests pin it to UTC). func newEnv(t *testing.T) *env { t.Helper() - time.Local = time.UTC e := &env{l: store.Layout{Root: t.TempDir()}, now: time.Date(2026, 9, 25, 14, 0, 0, 0, time.UTC)} ring := trust.NewRing(nil, []ed25519.PublicKey{releaseKey.Public().(ed25519.PublicKey)}) e.im = importer.New(importer.Deps{ - Layout: e.l, DeviceID: "board", AgentVersion: "0.3.0", + Layout: e.l, Config: config.InMemory(config.Config{DeviceID: "board"}), AgentVersion: "0.3.0", Ring: func() (*trust.Ring, error) { return ring, nil }, Now: func() time.Time { return e.now }, }) @@ -46,12 +52,18 @@ func newEnv(t *testing.T) *env { return e } -func (e *env) newScheduler() *Scheduler { - return New(Deps{ - Layout: e.l, Importer: e.im, Hour: 23, +// newScheduler builds a scheduler for e; opts adjust its Deps (channels are +// off unless one sets them). +func (e *env) newScheduler(opts ...func(*Deps)) *Scheduler { + d := Deps{ + Layout: e.l, Importer: e.im, Hour: 23, AgentVersion: "0.3.0", Changed: func(i Info) { e.got = append(e.got, i) }, Now: func() time.Time { return e.now }, - }) + } + for _, o := range opts { + o(&d) + } + return New(d) } func setApp(t *testing.T, l store.Layout, v string) { @@ -238,7 +250,8 @@ func TestRestartKeepsWaitingUpdates(t *testing.T) { func TestCheckAndInstall(t *testing.T) { e := newEnv(t) - e.s.d.Check = func(context.Context) error { return e.s.Offer(e.app(t, "2.1.0", 2)) } + cs := newChannelServer(t, "2.1.0", appPackageBytes(t, "2.1.0")) + e.s = e.newScheduler(func(d *Deps) { d.AppChannel = cs.URL + "/channel.json" }) out := e.s.CheckAndInstall(context.Background()) if out.CheckError != "" || len(out.Results) != 1 || out.Results[0].Action != importer.ActionInstalled { t.Fatalf("outcome = %+v", out) @@ -253,10 +266,14 @@ func TestInfoReportsTheLastCheck(t *testing.T) { if i := e.s.Info(); i.LastCheckAt != nil || i.LastCheckError != "" { t.Fatalf("before any check: %+v", i) } - e.s.d.Check = func(context.Context) error { return errors.New("github.com: no route to host") } + down := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + http.Error(w, "down", http.StatusBadGateway) + })) + defer down.Close() + e.s = e.newScheduler(func(d *Deps) { d.AppChannel = down.URL + "/channel.json" }) e.s.CheckAndInstall(context.Background()) i := e.s.Info() - if i.LastCheckAt == nil || i.LastCheckError != "github.com: no route to host" { + if i.LastCheckAt == nil || !strings.Contains(i.LastCheckError, "channel returned 502") { t.Fatalf("after a failed check: %+v", i) } e.s.CheckDone(nil) diff --git a/internal/uploadserver/listen_linux.go b/internal/core/uploadserver/listen_linux.go similarity index 100% rename from internal/uploadserver/listen_linux.go rename to internal/core/uploadserver/listen_linux.go diff --git a/internal/uploadserver/listen_other.go b/internal/core/uploadserver/listen_other.go similarity index 100% rename from internal/uploadserver/listen_other.go rename to internal/core/uploadserver/listen_other.go diff --git a/internal/uploadserver/page.go b/internal/core/uploadserver/page.go similarity index 100% rename from internal/uploadserver/page.go rename to internal/core/uploadserver/page.go diff --git a/internal/uploadserver/server.go b/internal/core/uploadserver/server.go similarity index 94% rename from internal/uploadserver/server.go rename to internal/core/uploadserver/server.go index 9e760a7..40ebda7 100644 --- a/internal/uploadserver/server.go +++ b/internal/core/uploadserver/server.go @@ -28,13 +28,13 @@ import ( "strconv" "time" - "github.com/LensBridge/agent/internal/clock" - "github.com/LensBridge/agent/internal/fsutil" - "github.com/LensBridge/agent/internal/importer" - "github.com/LensBridge/agent/internal/localserver" - "github.com/LensBridge/agent/internal/mbu" - "github.com/LensBridge/agent/internal/notice" - "github.com/LensBridge/agent/internal/store" + "github.com/LensBridge/agent/internal/core/clock" + "github.com/LensBridge/agent/internal/core/fsutil" + "github.com/LensBridge/agent/internal/core/importer" + "github.com/LensBridge/agent/internal/core/localserver" + "github.com/LensBridge/agent/internal/core/mbu" + "github.com/LensBridge/agent/internal/core/notice" + "github.com/LensBridge/agent/internal/core/store" ) // ServiceIP is the board's address on the service port; setup.sh and the @@ -58,8 +58,9 @@ type ClockReport struct { // Deps is what the server needs. type Deps struct { - Layout store.Layout - DeviceID string + Layout store.Layout + // DeviceID is the board's, read for every status. + DeviceID func() string AgentVersion string Importer *importer.Importer // ApplyClientTime is the clock keeper's decision on X-MB-Client-Time. @@ -84,6 +85,9 @@ func New(d Deps) *Server { if d.Logger == nil { d.Logger = slog.New(slog.DiscardHandler) } + if d.DeviceID == nil { + d.DeviceID = func() string { return "" } + } return &Server{d: d} } @@ -155,7 +159,7 @@ type Status struct { func (s *Server) status() Status { now := s.d.Now() - ls := localserver.BuildStatus(s.d.Layout, s.d.DeviceID, s.d.AgentVersion, now) + ls := localserver.BuildStatus(s.d.Layout, s.d.DeviceID(), s.d.AgentVersion, now) st := Status{DeviceID: ls.DeviceID, AgentVersion: ls.AgentVersion, App: ls.App, Content: ls.Content, Today: ls.Today, DaysRemaining: ls.DaysRemaining, StaleDays: ls.StaleDays} st.Clock.Unix = now.Unix() diff --git a/internal/uploadserver/server_test.go b/internal/core/uploadserver/server_test.go similarity index 84% rename from internal/uploadserver/server_test.go rename to internal/core/uploadserver/server_test.go index f200fa2..615fab1 100644 --- a/internal/uploadserver/server_test.go +++ b/internal/core/uploadserver/server_test.go @@ -9,10 +9,11 @@ import ( "net/http/httptest" "testing" - "github.com/LensBridge/agent/internal/importer" - "github.com/LensBridge/agent/internal/mbu" - "github.com/LensBridge/agent/internal/store" - "github.com/LensBridge/agent/internal/trust" + "github.com/LensBridge/agent/internal/core/config" + "github.com/LensBridge/agent/internal/core/importer" + "github.com/LensBridge/agent/internal/core/mbu" + "github.com/LensBridge/agent/internal/core/store" + "github.com/LensBridge/agent/internal/core/trust" ) var rk = ed25519.NewKeyFromSeed(bytes.Repeat([]byte{2}, 32)) @@ -29,10 +30,10 @@ func appPkg(t *testing.T, version string) []byte { func server(t *testing.T) (*Server, *int64) { l := store.Layout{Root: t.TempDir()} ring := trust.NewRing(nil, []ed25519.PublicKey{rk.Public().(ed25519.PublicKey)}) - im := importer.New(importer.Deps{Layout: l, DeviceID: "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b", AgentVersion: "0.2.0", + im := importer.New(importer.Deps{Layout: l, Config: config.InMemory(config.Config{DeviceID: "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b"}), AgentVersion: "0.2.0", Ring: func() (*trust.Ring, error) { return ring, nil }}) var got int64 - return New(Deps{Layout: l, DeviceID: "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b", Importer: im, + return New(Deps{Layout: l, DeviceID: func() string { return "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b" }, Importer: im, ApplyClientTime: func(unix int64, b importer.Batch) ClockReport { if b.Verified { got = unix diff --git a/internal/usbimport/fs_unix.go b/internal/core/usbimport/fs_unix.go similarity index 65% rename from internal/usbimport/fs_unix.go rename to internal/core/usbimport/fs_unix.go index ac45e11..95fdec2 100644 --- a/internal/usbimport/fs_unix.go +++ b/internal/core/usbimport/fs_unix.go @@ -27,15 +27,3 @@ func openRegularNoFollow(path string) (*os.File, error) { } return f, nil } - -// chownToDirOwner gives path the owner and group of dir. Best effort: the -// helper runs as root, and the inbox belongs to the daemon's user. -func chownToDirOwner(path, dir string) { - fi, err := os.Stat(dir) - if err != nil { - return - } - if st, ok := fi.Sys().(*syscall.Stat_t); ok { - _ = os.Chown(path, int(st.Uid), int(st.Gid)) - } -} diff --git a/internal/usbimport/fs_windows.go b/internal/core/usbimport/fs_windows.go similarity index 90% rename from internal/usbimport/fs_windows.go rename to internal/core/usbimport/fs_windows.go index cc505b5..e5e8c60 100644 --- a/internal/usbimport/fs_windows.go +++ b/internal/core/usbimport/fs_windows.go @@ -20,5 +20,3 @@ func openRegularNoFollow(path string) (*os.File, error) { } return os.Open(path) } - -func chownToDirOwner(string, string) {} diff --git a/internal/usbimport/usbimport.go b/internal/core/usbimport/usbimport.go similarity index 93% rename from internal/usbimport/usbimport.go rename to internal/core/usbimport/usbimport.go index 8e97afb..6908463 100644 --- a/internal/usbimport/usbimport.go +++ b/internal/core/usbimport/usbimport.go @@ -30,16 +30,21 @@ import ( "strings" "time" - "github.com/LensBridge/agent/internal/fsutil" - "github.com/LensBridge/agent/internal/importer" - "github.com/LensBridge/agent/internal/mbu" - "github.com/LensBridge/agent/internal/notice" - "github.com/LensBridge/agent/internal/store" + "github.com/LensBridge/agent/internal/core/fsutil" + "github.com/LensBridge/agent/internal/core/importer" + "github.com/LensBridge/agent/internal/core/mbu" + "github.com/LensBridge/agent/internal/core/notice" + "github.com/LensBridge/agent/internal/core/store" ) const ( - // MaxFiles is the most packages taken from one stick. - MaxFiles = 16 + // MaxFiles is the most packages taken from one stick. A USB kit from + // LensBridge for 20 boards holds 42: a setup file and a content package + // per board, the board app and the agent. Every board copies them all + // and ignores what is not for it. + MaxFiles = 64 + // MaxTotalBytes bounds what is copied from one stick onto the SD card. + MaxTotalBytes = 4 << 30 // DefaultMountRoot holds one mount point per device. DefaultMountRoot = "/run/musallahboard/usb" // WaitTimeout bounds how long the helper waits for the daemon. An agent @@ -82,7 +87,7 @@ func New() *Helper { MountRoot: DefaultMountRoot, DevDir: "/dev", Exec: runCommand, - Chown: chownToDirOwner, + Chown: fsutil.ChownToDirOwner, Logf: func(f string, a ...any) { fmt.Printf(f+"\n", a...) }, WaitTimeout: WaitTimeout, Poll: time.Second, @@ -228,7 +233,7 @@ type Candidate struct { // Scan lists the packages to take from the stick mounted at root: regular // files (never symlinks) named *.mbu in any case, at the top level and in a // top-level folder named MusallahBoard in any case, at most MaxFiles, each at -// most mbu.MaxPackageBytes. notes explains anything skipped. +// most mbu.MaxPackageBytes, together at most MaxTotalBytes. notes explains anything skipped. func Scan(root string) (files []Candidate, notes []string) { dirs := []string{root} if entries, err := os.ReadDir(root); err == nil { @@ -277,7 +282,17 @@ func Scan(root string) (files []Candidate, notes []string) { } all = all[:MaxFiles] } - return all, notes + var total int64 + kept := all[:0] + for _, c := range all { + if total+c.Size > MaxTotalBytes { + notes = append(notes, fmt.Sprintf("skipping %s: at most %d GiB is taken from one stick", rel(root, c.Path), MaxTotalBytes>>30)) + continue + } + total += c.Size + kept = append(kept, c) + } + return kept, notes } func rel(root, p string) string { diff --git a/internal/usbimport/usbimport_test.go b/internal/core/usbimport/usbimport_test.go similarity index 94% rename from internal/usbimport/usbimport_test.go rename to internal/core/usbimport/usbimport_test.go index d109455..6fdae9d 100644 --- a/internal/usbimport/usbimport_test.go +++ b/internal/core/usbimport/usbimport_test.go @@ -12,9 +12,9 @@ import ( "testing" "time" - "github.com/LensBridge/agent/internal/importer" - "github.com/LensBridge/agent/internal/notice" - "github.com/LensBridge/agent/internal/store" + "github.com/LensBridge/agent/internal/core/importer" + "github.com/LensBridge/agent/internal/core/notice" + "github.com/LensBridge/agent/internal/core/store" ) func touch(t *testing.T, p string, size int) { @@ -79,6 +79,18 @@ func TestScanLimits(t *testing.T) { t.Fatalf("notes = %q", notes) } + // The stick's total is bounded too (sparse files: nothing is written). + root = t.TempDir() + for i := range 9 { + f, _ := os.Create(filepath.Join(root, fmt.Sprintf("c%d.mbu", i))) + f.Truncate(500 << 20) + f.Close() + } + files, notes = Scan(root) + if len(files) != 8 || len(notes) != 1 || !strings.Contains(notes[0], "GiB") { + t.Fatalf("total cap: %d files, notes=%q", len(files), notes) + } + // A file over the package limit is skipped without reading it (sparse). root = t.TempDir() big := filepath.Join(root, "big.mbu") diff --git a/internal/enroll/chown_unix.go b/internal/enroll/chown_unix.go deleted file mode 100644 index 1daf996..0000000 --- a/internal/enroll/chown_unix.go +++ /dev/null @@ -1,36 +0,0 @@ -//go:build !windows - -package enroll - -import ( - "os" - "syscall" -) - -// chownToDirOwner sets the uid/gid of `path` to match the uid/gid of its -// parent directory. -// -// Rationale: enrollment is typically run via `sudo musallahboard-agent enroll`, -// which writes files as root:root. But the daemon runs as the service user -// (`musallahdaemon`), and would fail to read its own key. The install scripts -// pre-create /etc/musallahboard owned by the service user, so chowning new -// files to match the directory's owner gives the daemon read access without -// the caller needing to know which user that is. -// -// Best-effort: returns nil if `path` doesn't exist, if we can't stat the dir, -// or if we lack CAP_CHOWN (e.g. enroll was run as a non-root user that -// already owns the dir — in which case the file is already owned correctly). -func chownToDirOwner(path, dir string) error { - di, err := os.Stat(dir) - if err != nil { - return nil - } - st, ok := di.Sys().(*syscall.Stat_t) - if !ok { - return nil - } - // If we're not root, chown will fail with EPERM unless we already own - // the file — in which case it's a no-op anyway. Swallow the error. - _ = os.Chown(path, int(st.Uid), int(st.Gid)) - return nil -} diff --git a/internal/enroll/chown_windows.go b/internal/enroll/chown_windows.go deleted file mode 100644 index 09a4d9f..0000000 --- a/internal/enroll/chown_windows.go +++ /dev/null @@ -1,7 +0,0 @@ -//go:build windows - -package enroll - -// chownToDirOwner is a no-op on Windows; the daemon does not target Windows -// hosts, and Unix uid/gid semantics don't apply. -func chownToDirOwner(_, _ string) error { return nil } diff --git a/internal/kioskurl/chown_unix.go b/internal/kioskurl/chown_unix.go deleted file mode 100644 index b3c2282..0000000 --- a/internal/kioskurl/chown_unix.go +++ /dev/null @@ -1,27 +0,0 @@ -//go:build !windows - -package kioskurl - -import ( - "os" - "syscall" -) - -// chownToDirOwner sets the uid/gid of `path` to match its parent directory's -// owner. Same rationale as internal/enroll.chownToDirOwner: enrollment may run -// as root via sudo, but the daemon runs as the service user; matching the -// pre-created config dir's owner keeps the file readable without the caller -// needing to know which user that is. Best-effort — EPERM when we already own -// the file is harmless. -func chownToDirOwner(path, dir string) error { - di, err := os.Stat(dir) - if err != nil { - return nil - } - st, ok := di.Sys().(*syscall.Stat_t) - if !ok { - return nil - } - _ = os.Chown(path, int(st.Uid), int(st.Gid)) - return nil -} diff --git a/internal/kioskurl/chown_windows.go b/internal/kioskurl/chown_windows.go deleted file mode 100644 index 01f5b4c..0000000 --- a/internal/kioskurl/chown_windows.go +++ /dev/null @@ -1,7 +0,0 @@ -//go:build windows - -package kioskurl - -// chownToDirOwner is a no-op on Windows; the daemon only targets Linux Pis. -// This stub exists so the package builds for dev tooling on Windows. -func chownToDirOwner(_, _ string) error { return nil } diff --git a/internal/kioskurl/kioskurl.go b/internal/kioskurl/kioskurl.go deleted file mode 100644 index b4d2afd..0000000 --- a/internal/kioskurl/kioskurl.go +++ /dev/null @@ -1,61 +0,0 @@ -// Package kioskurl persists the URL the on-device kiosk browser loads, where -// the cage/Chromium launcher can read it. -// -// In v2 every board is served by its own agent (docs/architecture.md, -// section 14), so once a device is enrolled the URL is always the local -// server, with no query string: the page asks the agent who it is. The file -// doubles as the launcher's enrollment sentinel: until it exists the kiosk -// shows the "waiting for enrollment" splash, and the systemd .path watcher -// restarts the kiosk when it appears or changes. -package kioskurl - -import ( - "fmt" - "os" - "path/filepath" -) - -// DefaultOutPath is the URL the kiosk launcher reads. It is also the -// enrollment sentinel the kiosk waits on. -const DefaultOutPath = "/etc/musallahboard/kiosk-url" - -// LocalURL is the agent's local server. It must match -// localserver.BaseURL; a test checks. -const LocalURL = "http://127.0.0.1:8080/" - -// WriteLocal writes LocalURL to outPath (0644 so the unprivileged kiosk user -// can read it across the 0751 config dir). An unchanged file is not -// rewritten, so a restart of the agent never bounces the kiosk. -func WriteLocal(outPath string) error { - if outPath == "" { - return fmt.Errorf("kioskurl: empty path") - } - return writeURL(outPath, LocalURL) -} - -// writeURL atomically writes u (plus a trailing newline) to outPath. -func writeURL(outPath, u string) error { - composed := u + "\n" - - // Skip the write entirely when the composed URL is unchanged. The kiosk - // reload is driven by a systemd.path unit watching outPath; an identical - // rewrite (every daemon startup re-composes this) would needlessly cycle - // the kiosk on an already-enrolled device. Only a real change should fire - // the watcher. - if existing, err := os.ReadFile(outPath); err == nil && string(existing) == composed { - return nil - } - - tmp := outPath + ".tmp" - if err := os.WriteFile(tmp, []byte(composed), 0o644); err != nil { - return fmt.Errorf("kioskurl: write %s: %w", tmp, err) - } - if err := os.Rename(tmp, outPath); err != nil { - os.Remove(tmp) - return fmt.Errorf("kioskurl: rename %s: %w", outPath, err) - } - // WriteFile honours umask; force the mode so the kiosk user can always read. - _ = os.Chmod(outPath, 0o644) - _ = chownToDirOwner(outPath, filepath.Dir(outPath)) - return nil -} diff --git a/internal/kioskurl/kioskurl_test.go b/internal/kioskurl/kioskurl_test.go deleted file mode 100644 index f67c96a..0000000 --- a/internal/kioskurl/kioskurl_test.go +++ /dev/null @@ -1,37 +0,0 @@ -package kioskurl - -import ( - "os" - "path/filepath" - "testing" - "time" -) - -func TestWriteLocal(t *testing.T) { - out := filepath.Join(t.TempDir(), "kiosk-url") - if err := WriteLocal(out); err != nil { - t.Fatal(err) - } - got, _ := os.ReadFile(out) - if string(got) != LocalURL+"\n" { - t.Fatalf("kiosk-url = %q", got) - } - fi, _ := os.Stat(out) - // An identical rewrite must not touch the file: the kiosk .path watcher - // would restart the browser. - old := time.Now().Add(-time.Hour) - os.Chtimes(out, old, old) - if err := WriteLocal(out); err != nil { - t.Fatal(err) - } - fi2, _ := os.Stat(out) - if !fi2.ModTime().Equal(old) || fi.Mode().Perm() != 0o644 { - t.Fatalf("rewrote an unchanged kiosk-url, or wrong mode %v", fi.Mode()) - } -} - -func TestWriteLocalRejectsEmpty(t *testing.T) { - if err := WriteLocal(""); err == nil { - t.Fatal("expected an error") - } -} diff --git a/internal/netinfo/netinfo_test.go b/internal/netinfo/netinfo_test.go deleted file mode 100644 index e998696..0000000 --- a/internal/netinfo/netinfo_test.go +++ /dev/null @@ -1,88 +0,0 @@ -package netinfo - -import ( - "slices" - "testing" -) - -func TestRoutableIPv4DropsLinkLocal(t *testing.T) { - tests := []struct { - name string - in []string - want []string - }{ - { - name: "keeps private lan addresses", - in: []string{"192.168.1.42", "10.0.0.7", "172.16.3.1"}, - want: []string{"192.168.1.42", "10.0.0.7", "172.16.3.1"}, - }, - { - // A 169.254.x address means DHCP never answered. Nothing on the LAN - // can reach it, so it must never reach the enrollment splash. - name: "drops apipa", - in: []string{"169.254.11.9", "192.168.1.42"}, - want: []string{"192.168.1.42"}, - }, - { - name: "apipa only yields nothing", - in: []string{"169.254.11.9"}, - want: nil, - }, - { - name: "drops unparseable", - in: []string{"not-an-ip", "192.168.1.42"}, - want: []string{"192.168.1.42"}, - }, - { - name: "empty input", - in: nil, - want: nil, - }, - } - - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - got := routableIPv4(tt.in) - if !slices.Equal(got, tt.want) { - t.Errorf("routableIPv4(%v) = %v, want %v", tt.in, got, tt.want) - } - }) - } -} - -func TestInfoEqual(t *testing.T) { - base := Info{IPv4: []string{"192.168.1.42"}, SSID: "MSA", Hostname: "lobby"} - - tests := []struct { - name string - other Info - want bool - }{ - {"identical", Info{IPv4: []string{"192.168.1.42"}, SSID: "MSA", Hostname: "lobby"}, true}, - {"ip changed", Info{IPv4: []string{"192.168.1.43"}, SSID: "MSA", Hostname: "lobby"}, false}, - {"ip added", Info{IPv4: []string{"192.168.1.42", "10.0.0.7"}, SSID: "MSA", Hostname: "lobby"}, false}, - {"ssid changed", Info{IPv4: []string{"192.168.1.42"}, SSID: "Guest", Hostname: "lobby"}, false}, - {"hostname changed", Info{IPv4: []string{"192.168.1.42"}, SSID: "MSA", Hostname: "hall"}, false}, - {"went offline", Info{SSID: "MSA", Hostname: "lobby"}, false}, - } - - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - if got := base.Equal(tt.other); got != tt.want { - t.Errorf("Equal() = %v, want %v", got, tt.want) - } - }) - } -} - -func TestInfoOnline(t *testing.T) { - if (Info{}).Online() { - t.Error("empty Info reported online") - } - if (Info{IPv4: []string{}}).Online() { - t.Error("Info with zero addresses reported online") - } - if !(Info{IPv4: []string{"192.168.1.42"}}).Online() { - t.Error("Info with an address reported offline") - } -} diff --git a/internal/api/client.gen.go b/internal/online/api/client.gen.go similarity index 100% rename from internal/api/client.gen.go rename to internal/online/api/client.gen.go diff --git a/internal/api/doc.go b/internal/online/api/doc.go similarity index 76% rename from internal/api/doc.go rename to internal/online/api/doc.go index 4bc320e..34c9bd6 100644 --- a/internal/api/doc.go +++ b/internal/online/api/doc.go @@ -3,10 +3,10 @@ // // Do not edit client.gen.go. To pick up a backend change: // -// go generate ./internal/api +// go generate ./internal/online/api // // The generated file is committed, per Go convention, so a plain `go build` // needs no code generation step and the diff is reviewable. // -//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@v2.8.0 -config oapi-codegen.yaml ../../../../LensBridgeBackend/openapi.yaml +//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@v2.8.0 -config oapi-codegen.yaml ../../../../../LensBridgeBackend/openapi.yaml package api diff --git a/internal/api/oapi-codegen.yaml b/internal/online/api/oapi-codegen.yaml similarity index 100% rename from internal/api/oapi-codegen.yaml rename to internal/online/api/oapi-codegen.yaml diff --git a/internal/boardsync/boardsync.go b/internal/online/boardsync/boardsync.go similarity index 72% rename from internal/boardsync/boardsync.go rename to internal/online/boardsync/boardsync.go index 6d31fa1..f45c65f 100644 --- a/internal/boardsync/boardsync.go +++ b/internal/online/boardsync/boardsync.go @@ -1,7 +1,7 @@ -// Package boardsync keeps an online board's local state fresh from the -// network (docs/architecture.md, sections 7 and 9): content from the -// LensBridge backend, the live weather overlay, and new board app and agent -// releases from the release channels. +// Package boardsync keeps an enrolled board's content fresh from the +// LensBridge backend (docs/architecture.md, sections 7 and 9): the content +// package and the live weather overlay. (New board app and agent releases +// come from the release channels, package updates, which need no backend.) // // Nothing here is trusted. Everything that changes the board arrives as a // signed package and goes through the same importer as a USB stick or an @@ -17,7 +17,7 @@ import ( "fmt" "io" "log/slog" - "net" + "math/rand" "net/http" "os" "path/filepath" @@ -25,31 +25,28 @@ import ( "sync" "time" - "github.com/LensBridge/agent/internal/config" - "github.com/LensBridge/agent/internal/importer" - "github.com/LensBridge/agent/internal/mbu" - "github.com/LensBridge/agent/internal/store" + "github.com/LensBridge/agent/internal/core/config" + "github.com/LensBridge/agent/internal/core/fsutil" + "github.com/LensBridge/agent/internal/core/importer" + "github.com/LensBridge/agent/internal/core/mbu" + "github.com/LensBridge/agent/internal/core/netinfo" + "github.com/LensBridge/agent/internal/core/store" + "github.com/LensBridge/agent/internal/online/devauth" ) // Timings from the contract. They are fields on the Syncer (set from these in // New) so tests can shrink them. const ( - ContentInterval = 30 * time.Minute + ContentInterval = 30 * time.Minute + // TriggerDelay and TriggerJitter: a requested sync (the backend's + // content_changed frame, config.refresh) runs TriggerDelay plus up to + // TriggerJitter later, so a fleet told at once does not sync at once. TriggerDelay = 10 * time.Second + TriggerJitter = 20 * time.Second ContentMinBackoff = time.Minute ContentMaxBackoff = 30 * time.Minute WeatherInterval = 30 * time.Minute WeatherMaxAge = 3 * time.Hour - ChannelFirstDelay = 2 * time.Minute - ChannelInterval = 6 * time.Hour - // ChannelRetry is the first retry after a failed channel check. It - // doubles on each failure, up to ChannelInterval. - ChannelRetry = 5 * time.Minute - // ChannelTimeout bounds one fetch of a channel file, which is a few - // hundred bytes: a request that has had no answer by then is stuck. - ChannelTimeout = 30 * time.Second - RefreshMinBackoff = time.Second - RefreshMaxBackoff = 5 * time.Minute // MaxHaveMedia caps the haveMedia list. A store bigger than this only // costs a larger download; the backend includes whatever is not listed. @@ -57,38 +54,22 @@ const ( // maxErrorBody bounds how much of an error response is read for its // message. maxErrorBody = 4 << 10 - // maxChannelBytes bounds a channel pointer file. - maxChannelBytes = 1 << 20 // maxWeatherResponse bounds GET /api/agent/weather's answer. maxWeatherResponse = 1 << 20 ) // Deps is what a Syncer needs. type Deps struct { - Cfg *config.Config - Key ed25519.PrivateKey - Layout store.Layout - Importer *importer.Importer - // Updates holds software from the release channels until it installs. - Updates Updates + Cfg *config.Config + Key ed25519.PrivateKey + Layout store.Layout + Importer *importer.Importer AgentVersion string Logger *slog.Logger // HTTP is optional; New builds one with sane timeouts. HTTP *http.Client } -// Updates is the update scheduler (package updates) as the release channels -// see it. -type Updates interface { - // Pending is the version of kind already waiting to install, or "". - Pending(kind mbu.Type) string - // Offer verifies a downloaded package and keeps it until its install - // window. The file must be on the same filesystem as the store. - Offer(file string) error - // CheckDone records how a channel check went, for the status. - CheckDone(err error) -} - // Status is the "sync" object of /api/local/status. type Status struct { Enabled bool `json:"enabled"` @@ -106,9 +87,8 @@ type Syncer struct { now func() time.Time contentInterval, triggerDelay, minBackoff, maxBackoff time.Duration - weatherInterval, channelFirstDelay, channelInterval time.Duration - channelRetry, channelTimeout time.Duration - refreshMinBackoff, refreshMaxBackoff time.Duration + triggerJitter time.Duration + weatherInterval time.Duration mu sync.Mutex status Status @@ -124,52 +104,20 @@ func New(d Deps) *Syncer { } client := d.HTTP if client == nil { - client = NewHTTPClient() + client = netinfo.NewHTTPClient() } return &Syncer{ - d: d, - log: log.With("component", "sync"), - client: client, - trigger: make(chan struct{}, 1), - now: time.Now, - contentInterval: ContentInterval, - triggerDelay: TriggerDelay, - minBackoff: ContentMinBackoff, - maxBackoff: ContentMaxBackoff, - weatherInterval: WeatherInterval, - channelFirstDelay: ChannelFirstDelay, - channelInterval: ChannelInterval, - channelRetry: ChannelRetry, - channelTimeout: ChannelTimeout, - refreshMinBackoff: RefreshMinBackoff, - refreshMaxBackoff: RefreshMaxBackoff, - } -} - -// NewHTTPClient is the client every sync request uses: a bounded connect so -// a board with no route gives up fast, and an overall limit long enough for -// a large package on a slow link. -// -// HTTP/2 connections are health-checked with pings. Without them a -// connection that died silently (a NAT or firewall dropping it, a Wi-Fi -// roam) stays in the pool, and every request to that host waits on it until -// ResponseHeaderTimeout ("http2: timeout awaiting response headers"). -func NewHTTPClient() *http.Client { - return &http.Client{ - Timeout: 10 * time.Minute, - Transport: &http.Transport{ - Proxy: http.ProxyFromEnvironment, - DialContext: (&net.Dialer{Timeout: 15 * time.Second, KeepAlive: 30 * time.Second}).DialContext, - TLSHandshakeTimeout: 15 * time.Second, - ResponseHeaderTimeout: 2 * time.Minute, - IdleConnTimeout: 90 * time.Second, - MaxIdleConns: 4, - ForceAttemptHTTP2: true, - HTTP2: &http.HTTP2Config{ - SendPingTimeout: 30 * time.Second, - PingTimeout: 15 * time.Second, - }, - }, + d: d, + log: log.With("component", "sync"), + client: client, + trigger: make(chan struct{}, 1), + now: time.Now, + contentInterval: ContentInterval, + triggerDelay: TriggerDelay, + triggerJitter: TriggerJitter, + minBackoff: ContentMinBackoff, + maxBackoff: ContentMaxBackoff, + weatherInterval: WeatherInterval, } } @@ -183,22 +131,16 @@ func (s *Syncer) Run(ctx context.Context) { } if s.d.Cfg.ContentSync() { run(s.contentLoop) - run(s.refreshLoop) run(s.weatherLoop) } else { s.log.Info("content sync is off (content_sync = false); the board only takes content from USB, uploads and the CLI") } - if s.d.Cfg.AutoUpdate() { - run(s.channelLoop) - } else { - s.log.Info("release channels are off (auto_update = false)") - } wg.Wait() } -// Trigger asks for a content sync in TriggerDelay. Calls within that window -// fold into one sync: the backend's refresh channel fires once per admin -// edit, and an admin editing five posters should cost one download. +// Trigger asks for a content sync in TriggerDelay plus up to TriggerJitter. +// Calls before it runs fold into one sync: an admin editing five posters +// should cost one download. func (s *Syncer) Trigger() { select { case s.trigger <- struct{}{}: @@ -240,10 +182,14 @@ func (s *Syncer) contentLoop(ctx context.Context) { case <-s.trigger: // Bring the next sync forward to at most triggerDelay away, but // never push an already-closer one back: a steady stream of - // refresh messages must not postpone the sync forever. - if until := deadline.Sub(s.now()); until > s.triggerDelay { - deadline = s.now().Add(s.triggerDelay) - resetTimer(timer, s.triggerDelay) + // triggers must not postpone the sync forever. + d := s.triggerDelay + if s.triggerJitter > 0 { + d += time.Duration(rand.Int63n(int64(s.triggerJitter))) + } + if until := deadline.Sub(s.now()); until > d { + deadline = s.now().Add(d) + resetTimer(timer, d) } continue case <-timer.C: @@ -330,7 +276,7 @@ func (s *Syncer) syncContent(ctx context.Context) error { } req.Header.Set("Content-Type", "application/json") req.Header.Set("Accept", "application/vnd.musallahboard.mbu") - signRequest(req, body, s.d.Cfg.DeviceID, s.d.Key, s.now()) + devauth.Sign(req, body, s.d.Cfg.DeviceID, s.d.Key, s.now()) resp, err := s.do(req) if err != nil { s.log.Debug("content sync request failed", "err", err) @@ -347,12 +293,14 @@ func (s *Syncer) syncContent(ctx context.Context) error { } defer os.RemoveAll(dir) file := filepath.Join(dir, "content.mbu") - if _, err := saveCapped(file, resp.Body, maxPackage, nil); err != nil { - if errors.Is(err, errTooLarge) { - return err - } + // One byte past the limit tells "exactly at the limit" from "too big". + n, err := fsutil.CopyFileSync(file, resp.Body, mbu.MaxPackageBytes+1, 0o640) + if err != nil { return &syncError{short: "download from the backend was interrupted", detail: err} } + if n > mbu.MaxPackageBytes { + return fmt.Errorf("the backend's package is larger than %d MiB, the most a package may be", mbu.MaxPackageBytes>>20) + } b := s.d.Importer.Import(ctx, importer.SourceSync, []string{file}) return batchError(b) @@ -474,7 +422,7 @@ func (s *Syncer) FetchWeather(ctx context.Context) error { return err } req.Header.Set("Accept", "application/json") - signRequest(req, nil, s.d.Cfg.DeviceID, s.d.Key, s.now()) + devauth.Sign(req, nil, s.d.Cfg.DeviceID, s.d.Key, s.now()) resp, err := s.do(req) if err != nil { return err diff --git a/internal/online/boardsync/boardsync_test.go b/internal/online/boardsync/boardsync_test.go new file mode 100644 index 0000000..603c594 --- /dev/null +++ b/internal/online/boardsync/boardsync_test.go @@ -0,0 +1,352 @@ +package boardsync + +import ( + "bytes" + "context" + "crypto/ed25519" + "crypto/sha256" + "encoding/base64" + "encoding/hex" + "encoding/json" + "io" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "strconv" + "strings" + "sync/atomic" + "testing" + "time" + + "github.com/LensBridge/agent/internal/core/config" + "github.com/LensBridge/agent/internal/core/importer" + "github.com/LensBridge/agent/internal/core/mbu" + "github.com/LensBridge/agent/internal/core/store" + "github.com/LensBridge/agent/internal/core/trust" + "github.com/LensBridge/agent/internal/online/devauth" +) + +const testDevice = "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b" + +func seedKey(b byte) ed25519.PrivateKey { + return ed25519.NewKeyFromSeed(bytes.Repeat([]byte{b}, 32)) +} + +var ( + contentKey = seedKey(1) + releaseKey = seedKey(2) + deviceKey = seedKey(3) +) + +type env struct { + layout store.Layout + cfg *config.Config + syncer *Syncer +} + +func boolp(b bool) *bool { return &b } + +// newEnv builds a Syncer over a temp store with a real importer that trusts +// contentKey and releaseKey. +func newEnv(t *testing.T, backend string) *env { + t.Helper() + l := store.Layout{Root: t.TempDir()} + cfg := &config.Config{ + DeviceID: testDevice, + BackendURL: backend, + WebSocketURL: "ws://unused/api/agent/ws", + } + ring := trust.NewRing( + []ed25519.PublicKey{contentKey.Public().(ed25519.PublicKey)}, + []ed25519.PublicKey{releaseKey.Public().(ed25519.PublicKey)}, + ) + im := importer.New(importer.Deps{ + Layout: l, + Config: config.InMemory(config.Config{DeviceID: testDevice}), + AgentVersion: "0.3.0", + Ring: func() (*trust.Ring, error) { return ring, nil }, + }) + s := New(Deps{Cfg: cfg, Key: deviceKey, Layout: l, Importer: im, AgentVersion: "0.3.0"}) + return &env{layout: l, cfg: cfg, syncer: s} +} + +func build(t *testing.T, m mbu.Manifest, src []mbu.Source, key ed25519.PrivateKey) []byte { + t.Helper() + var buf bytes.Buffer + if err := mbu.Build(&buf, m, src, []ed25519.PrivateKey{key}); err != nil { + t.Fatalf("Build: %v", err) + } + return buf.Bytes() +} + +func contentPackage(t *testing.T, seq int64) []byte { + m := mbu.Manifest{ + Type: mbu.TypeContent, Sequence: seq, DeviceID: testDevice, + Content: &mbu.ContentInfo{Timezone: "America/Toronto", FirstDay: "2026-09-24", LastDay: "2026-09-25"}, + } + src := []mbu.Source{ + {Path: "payloads/2026-09-24.json", Data: []byte(`{"frames":[],"weather":null}`)}, + {Path: "payloads/2026-09-25.json", Data: []byte(`{"frames":[],"weather":null}`)}, + } + return build(t, m, src, contentKey) +} + +func TestSyncContentSignedAndImported(t *testing.T) { + pkg := contentPackage(t, 1000) + var gotBody struct { + Days int `json:"days"` + HaveMedia []string `json:"haveMedia"` + } + haveSHA := strings.Repeat("ab", 32) + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Method != http.MethodPost || r.URL.Path != "/api/agent/content-bundle" { + t.Errorf("unexpected %s %s", r.Method, r.URL.Path) + } + body, _ := io.ReadAll(r.Body) + if err := json.Unmarshal(body, &gotBody); err != nil { + t.Errorf("body: %v", err) + } + if r.Header.Get(devauth.HeaderDeviceID) != testDevice { + t.Errorf("device id header = %q", r.Header.Get(devauth.HeaderDeviceID)) + } + ts, err := strconv.ParseInt(r.Header.Get(devauth.HeaderTimestamp), 10, 64) + if err != nil || time.Since(time.UnixMilli(ts)).Abs() > time.Minute { + t.Errorf("timestamp header = %q", r.Header.Get(devauth.HeaderTimestamp)) + } + sig, _ := base64.StdEncoding.DecodeString(r.Header.Get(devauth.HeaderSignature)) + msg := devauth.Message(r.Method, r.URL.Path, testDevice, ts, body) + if !ed25519.Verify(deviceKey.Public().(ed25519.PublicKey), msg, sig) { + t.Error("signature does not verify over the received body") + } + if !strings.HasSuffix(string(msg), hexSHA(body)) { + t.Error("message does not end in the body hash") + } + w.Header().Set("Content-Type", "application/vnd.musallahboard.mbu") + w.Write(pkg) + })) + defer srv.Close() + + e := newEnv(t, srv.URL+"/") + // A media file already in the store must be offered as haveMedia. + os.MkdirAll(e.layout.MediaDir(), 0o750) + os.WriteFile(filepath.Join(e.layout.MediaDir(), haveSHA+".png"), []byte("x"), 0o640) + + if err := e.syncer.SyncContent(context.Background()); err != nil { + t.Fatalf("SyncContent: %v", err) + } + if gotBody.Days != 7 { + t.Errorf("days = %d, want 7", gotBody.Days) + } + if len(gotBody.HaveMedia) != 1 || gotBody.HaveMedia[0] != haveSHA { + t.Errorf("haveMedia = %v", gotBody.HaveMedia) + } + c, err := e.layout.CurrentContent() + if err != nil || c.Manifest.Sequence != 1000 || c.Info.Source != "sync" { + t.Fatalf("installed content = %+v, %v", c, err) + } + st := e.syncer.Status() + if !st.Enabled || st.LastSuccessAt == nil || st.LastAttemptAt == nil || st.LastError != nil { + t.Errorf("status = %+v", st) + } + if left, _ := filepath.Glob(filepath.Join(e.layout.Inbox(), ".sync-*")); len(left) != 0 { + t.Errorf("download dirs left behind: %v", left) + } + // The same package again is "unchanged", which is still a success. + if err := e.syncer.SyncContent(context.Background()); err != nil { + t.Fatalf("second SyncContent: %v", err) + } +} + +func hexSHA(b []byte) string { + s := sha256.Sum256(b) + return hex.EncodeToString(s[:]) +} + +func TestSyncContentErrors(t *testing.T) { + cases := []struct { + status int + body string + want string + }{ + {503, `{"message":"no content signing key configured"}`, "backend returned 503: no content signing key configured"}, + {401, `{"message":"unknown device"}`, "revoked, or the board's clock is wrong"}, + {500, `oops`, "backend returned 500"}, + } + for _, tc := range cases { + t.Run(strconv.Itoa(tc.status), func(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(tc.status) + io.WriteString(w, tc.body) + })) + defer srv.Close() + e := newEnv(t, srv.URL) + err := e.syncer.SyncContent(context.Background()) + if err == nil || !strings.Contains(err.Error(), tc.want) { + t.Fatalf("err = %v, want %q", err, tc.want) + } + st := e.syncer.Status() + if st.LastError == nil || *st.LastError != err.Error() || st.LastSuccessAt != nil { + t.Errorf("status = %+v", st) + } + }) + } +} + +func TestSyncContentUnreachable(t *testing.T) { + srv := httptest.NewServer(http.NotFoundHandler()) + url := srv.URL + srv.Close() + e := newEnv(t, url) + err := e.syncer.SyncContent(context.Background()) + if err == nil || err.Error() != "backend unreachable" { + t.Fatalf("err = %v", err) + } +} + +func TestSyncContentRejectedPackage(t *testing.T) { + // Signed by the release key: authentic to nobody for content. + m := mbu.Manifest{Type: mbu.TypeContent, Sequence: 5, DeviceID: testDevice, + Content: &mbu.ContentInfo{Timezone: "UTC", FirstDay: "2026-09-24", LastDay: "2026-09-24"}} + pkg := build(t, m, []mbu.Source{{Path: "payloads/2026-09-24.json", Data: []byte(`{}`)}}, releaseKey) + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.Write(pkg) })) + defer srv.Close() + e := newEnv(t, srv.URL) + err := e.syncer.SyncContent(context.Background()) + if err == nil || !strings.Contains(err.Error(), "refused") { + t.Fatalf("err = %v", err) + } +} + +func TestContentBackoff(t *testing.T) { + var hits atomic.Int32 + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path == "/api/agent/content-bundle" { + hits.Add(1) + } + w.WriteHeader(503) + })) + defer srv.Close() + e := newEnv(t, srv.URL) + s := e.syncer + s.minBackoff, s.maxBackoff = 20*time.Millisecond, 80*time.Millisecond + s.contentInterval = time.Hour + ctx, cancel := context.WithTimeout(context.Background(), 330*time.Millisecond) + defer cancel() + s.contentLoop(ctx) + // Attempts at about 0, 20, 60, 140, 220, 300 ms: doubling, then capped. + if n := hits.Load(); n < 4 || n > 8 { + t.Fatalf("%d attempts in 330 ms, want about 6", n) + } +} + +func TestTriggerFoldsIntoOneSync(t *testing.T) { + pkg := contentPackage(t, 1000) + var hits atomic.Int32 + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path != "/api/agent/content-bundle" { + http.NotFound(w, r) + return + } + hits.Add(1) + w.Write(pkg) + })) + defer srv.Close() + e := newEnv(t, srv.URL) + e.syncer.triggerDelay, e.syncer.triggerJitter = 50*time.Millisecond, 100*time.Millisecond + ctx, cancel := context.WithCancel(context.Background()) + done := make(chan struct{}) + go func() { e.syncer.Run(ctx); close(done) }() + deadline := time.Now().Add(10 * time.Second) + for hits.Load() < 1 && time.Now().Before(deadline) { + time.Sleep(10 * time.Millisecond) + } + // Triggers in quick succession fold into one sync, and it waits at + // least the delay. + asked := time.Now() + for range 5 { + e.syncer.Trigger() + time.Sleep(5 * time.Millisecond) + } + for hits.Load() < 2 && time.Now().Before(deadline) { + time.Sleep(time.Millisecond) + } + if waited := time.Since(asked); waited < e.syncer.triggerDelay { + t.Fatalf("synced %s after the trigger, before the delay", waited) + } + // Then long enough for any extra, unfolded sync to show up. + time.Sleep(4 * (e.syncer.triggerDelay + e.syncer.triggerJitter)) + cancel() + <-done + // One at start, one for the burst of triggers. + if n := hits.Load(); n != 2 { + t.Fatalf("%d content syncs, want 2", n) + } +} + +func TestWeather(t *testing.T) { + body := `{"weather":{"tempC":12,"icon":"sun"},"fetchedAt":"2026-09-24T12:00:00Z"}` + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path != "/api/agent/weather" || r.Method != http.MethodGet { + t.Errorf("unexpected %s %s", r.Method, r.URL) + } + if r.Header.Get("X-MB-Device-Id") != testDevice || r.Header.Get("X-MB-Signature") == "" { + t.Errorf("weather request is not device-signed: %v", r.Header) + } + io.WriteString(w, body) + })) + defer srv.Close() + e := newEnv(t, srv.URL) + s := e.syncer + now := time.Date(2026, 9, 24, 12, 0, 0, 0, time.UTC) + s.now = func() time.Time { return now } + + if _, ok := s.Weather(); ok { + t.Fatal("weather before any fetch") + } + if err := s.FetchWeather(context.Background()); err != nil { + t.Fatal(err) + } + w, ok := s.Weather() + if !ok || string(w) != `{"tempC":12,"icon":"sun"}` { + t.Fatalf("weather = %s, %v", w, ok) + } + now = now.Add(2*time.Hour + 59*time.Minute) + if _, ok := s.Weather(); !ok { + t.Fatal("weather expired early") + } + now = now.Add(time.Minute) + if _, ok := s.Weather(); ok { + t.Fatal("weather older than 3 h still served") + } + + // No weather object clears it. + body = `{"weather":null}` + s.FetchWeather(context.Background()) + if _, ok := s.Weather(); ok { + t.Fatal("null weather kept an old value") + } + body = `{"weather":[1,2]}` + s.FetchWeather(context.Background()) + if _, ok := s.Weather(); ok { + t.Fatal("non-object weather accepted") + } +} + +func TestContentSyncOff(t *testing.T) { + var hits atomic.Int32 + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { hits.Add(1) })) + defer srv.Close() + e := newEnv(t, srv.URL) + e.cfg.ContentSyncSet = boolp(false) + ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond) + defer cancel() + e.syncer.Run(ctx) + if hits.Load() != 0 { + t.Fatal("synced with content_sync off") + } + if e.syncer.Status().Enabled { + t.Fatal("status reports sync enabled with content_sync off") + } +} diff --git a/internal/commands/cache.go b/internal/online/commands/cache.go similarity index 100% rename from internal/commands/cache.go rename to internal/online/commands/cache.go diff --git a/internal/commands/cache_test.go b/internal/online/commands/cache_test.go similarity index 95% rename from internal/commands/cache_test.go rename to internal/online/commands/cache_test.go index 59aa0d7..3db5e80 100644 --- a/internal/commands/cache_test.go +++ b/internal/online/commands/cache_test.go @@ -32,7 +32,7 @@ func TestResultCache_GetPromotes(t *testing.T) { c := NewResultCache(2) c.Put("a", CachedResult{Status: "ok"}) c.Put("b", CachedResult{Status: "ok"}) - _, _ = c.Get("a") // promote a → MRU + _, _ = c.Get("a") // promote a → MRU c.Put("c", CachedResult{Status: "ok"}) // should now evict b, not a if _, ok := c.Get("a"); !ok { diff --git a/internal/commands/chrome_reload.go b/internal/online/commands/chrome_reload.go similarity index 87% rename from internal/commands/chrome_reload.go rename to internal/online/commands/chrome_reload.go index cbfae16..ecd1727 100644 --- a/internal/commands/chrome_reload.go +++ b/internal/online/commands/chrome_reload.go @@ -4,12 +4,12 @@ import ( "context" "encoding/json" - "github.com/LensBridge/agent/internal/cdp" + "github.com/LensBridge/agent/internal/core/kiosk" ) // ChromeReload triggers a hard reload of the kiosk page via CDP. type ChromeReload struct { - CDP *cdp.Client + CDP *kiosk.Client } func (h *ChromeReload) Kind() string { return "chrome.reload" } diff --git a/internal/commands/chrome_screenshot.go b/internal/online/commands/chrome_screenshot.go similarity index 94% rename from internal/commands/chrome_screenshot.go rename to internal/online/commands/chrome_screenshot.go index b529267..1a0ca77 100644 --- a/internal/commands/chrome_screenshot.go +++ b/internal/online/commands/chrome_screenshot.go @@ -5,7 +5,7 @@ import ( "encoding/json" "fmt" - "github.com/LensBridge/agent/internal/cdp" + "github.com/LensBridge/agent/internal/core/kiosk" ) // maxResultBase64 keeps the result frame under the backend's 10 MB WebSocket @@ -20,7 +20,7 @@ const maxResultBase64 = 8 << 20 // 8 MiB // blob into object storage and rewrite output to {"url":"..."}, but the // agent always returns inline base64. type ChromeScreenshot struct { - CDP *cdp.Client + CDP *kiosk.Client } func (h *ChromeScreenshot) Kind() string { return "chrome.screenshot" } diff --git a/internal/commands/config_refresh.go b/internal/online/commands/config_refresh.go similarity index 81% rename from internal/commands/config_refresh.go rename to internal/online/commands/config_refresh.go index 575c9d9..f9a5825 100644 --- a/internal/commands/config_refresh.go +++ b/internal/online/commands/config_refresh.go @@ -6,21 +6,19 @@ import ( "errors" "fmt" - "github.com/LensBridge/agent/internal/cdp" - "github.com/LensBridge/agent/internal/kioskurl" + "github.com/LensBridge/agent/internal/core/kiosk" ) // ConfigRefresh pulls fresh content and repaints the board in place, with no -// reload, so the screen never flashes. It re-asserts the on-disk kiosk URL -// (the local server), asks the content syncer for a sync, and asks the live -// page to re-fetch its payload. +// reload, so the screen never flashes. It asks the content syncer for a sync, +// and the live page to re-fetch its payload. // // The page contract is `window.MusallahBoard.refresh()` (see the frontend's // src/App.jsx), which resolves to {ok, deviceId, at | error}. The page learns // its device id from the agent's /api/local/status, so nothing is pushed into // it any more. type ConfigRefresh struct { - CDP *cdp.Client + CDP *kiosk.Client // Before, when set, runs first. The daemon passes the content syncer's // Trigger: the page only shows what the agent has installed, so a refresh // from the admin portal should also pull new content. @@ -51,10 +49,6 @@ func (h *ConfigRefresh) Execute(ctx context.Context, _ json.RawMessage, progress if h.Before != nil { h.Before() } - if err := kioskurl.WriteLocal(kioskurl.DefaultOutPath); err != nil { - progress("warn", "kiosk url not rewritten: "+err.Error(), nil) - } - progress("evaluating", "window.MusallahBoard.refresh()", nil) var res pageResult @@ -63,8 +57,8 @@ func (h *ConfigRefresh) Execute(ctx context.Context, _ json.RawMessage, progress // success is how this command once spent its life lying to the admin // portal: the board sat on stale content while the dashboard said // SUCCEEDED. - if errors.Is(err, cdp.ErrEvalUndefined) { - return nil, fmt.Errorf("kiosk page returned nothing: it is not the board (splash or update screen?)") + if errors.Is(err, kiosk.ErrEvalUndefined) { + return nil, fmt.Errorf("kiosk page returned nothing: it is not the board (setup screen or update screen?)") } if err != nil { return nil, err diff --git a/internal/commands/config_refresh_test.go b/internal/online/commands/config_refresh_test.go similarity index 100% rename from internal/commands/config_refresh_test.go rename to internal/online/commands/config_refresh_test.go diff --git a/internal/commands/dispatcher.go b/internal/online/commands/dispatcher.go similarity index 98% rename from internal/commands/dispatcher.go rename to internal/online/commands/dispatcher.go index 6988c05..05b2a2c 100644 --- a/internal/commands/dispatcher.go +++ b/internal/online/commands/dispatcher.go @@ -6,7 +6,7 @@ import ( "log/slog" "time" - "github.com/LensBridge/agent/internal/wsclient" + "github.com/LensBridge/agent/internal/online/wsclient" ) const ( diff --git a/internal/online/commands/kiosk_restart.go b/internal/online/commands/kiosk_restart.go new file mode 100644 index 0000000..ffed4c9 --- /dev/null +++ b/internal/online/commands/kiosk_restart.go @@ -0,0 +1,22 @@ +package commands + +import ( + "context" + "encoding/json" + + "github.com/LensBridge/agent/internal/core/kiosk" +) + +// KioskRestart bounces the musallahboard-kiosk systemd unit (kiosk.Restart), +// through the sudoers allow-list. +type KioskRestart struct{} + +func (h *KioskRestart) Kind() string { return "kiosk.restart" } + +func (h *KioskRestart) Execute(ctx context.Context, _ json.RawMessage, progress ProgressFn) (any, error) { + progress("restarting", "systemctl restart musallahboard-kiosk.service", nil) + if err := kiosk.Restart(ctx); err != nil { + return nil, err + } + return map[string]any{"restarted": true}, nil +} diff --git a/internal/commands/logs_tail.go b/internal/online/commands/logs_tail.go similarity index 100% rename from internal/commands/logs_tail.go rename to internal/online/commands/logs_tail.go diff --git a/internal/commands/registry.go b/internal/online/commands/registry.go similarity index 100% rename from internal/commands/registry.go rename to internal/online/commands/registry.go diff --git a/internal/commands/registry_test.go b/internal/online/commands/registry_test.go similarity index 96% rename from internal/commands/registry_test.go rename to internal/online/commands/registry_test.go index 7930da0..0d487e1 100644 --- a/internal/commands/registry_test.go +++ b/internal/online/commands/registry_test.go @@ -9,7 +9,7 @@ import ( "sync" "testing" - "github.com/LensBridge/agent/internal/wsclient" + "github.com/LensBridge/agent/internal/online/wsclient" ) type fakeHandler struct { @@ -24,10 +24,10 @@ func (f *fakeHandler) Execute(_ context.Context, _ json.RawMessage, _ ProgressFn } type fakeSender struct { - mu sync.Mutex - acks []string - progress []string - results []sentResult + mu sync.Mutex + acks []string + progress []string + results []sentResult } type sentResult struct { diff --git a/internal/commands/system_reboot.go b/internal/online/commands/system_reboot.go similarity index 100% rename from internal/commands/system_reboot.go rename to internal/online/commands/system_reboot.go diff --git a/internal/commands/update_install_now.go b/internal/online/commands/update_install_now.go similarity index 94% rename from internal/commands/update_install_now.go rename to internal/online/commands/update_install_now.go index 6fb1349..8069673 100644 --- a/internal/commands/update_install_now.go +++ b/internal/online/commands/update_install_now.go @@ -4,7 +4,7 @@ import ( "context" "encoding/json" - "github.com/LensBridge/agent/internal/updates" + "github.com/LensBridge/agent/internal/core/updates" ) // UpdateInstallNow checks the release channels and installs any new board app diff --git a/internal/devauth/devauth.go b/internal/online/devauth/devauth.go similarity index 100% rename from internal/devauth/devauth.go rename to internal/online/devauth/devauth.go diff --git a/internal/devauth/devauth_test.go b/internal/online/devauth/devauth_test.go similarity index 100% rename from internal/devauth/devauth_test.go rename to internal/online/devauth/devauth_test.go diff --git a/internal/online/enroll/claim.go b/internal/online/enroll/claim.go new file mode 100644 index 0000000..8de8676 --- /dev/null +++ b/internal/online/enroll/claim.go @@ -0,0 +1,126 @@ +package enroll + +import ( + "bytes" + "context" + "crypto/ed25519" + "crypto/hmac" + "crypto/sha256" + "encoding/base64" + "encoding/json" + "errors" + "fmt" + "io" + "net/http" + "os" + "strings" + "time" + + "github.com/LensBridge/agent/internal/core/mbu" + "github.com/LensBridge/agent/internal/online/api" +) + +// The claim (spec C2) binds the board's own device key to a device the +// admin created in the console, using the claim secret from its setup file +// instead of an enrollment token: +// +// POST /api/agent/claim +// {"deviceId", "publicKey": , "proof", "agentVersion", "hostname"} +// +// proof = base64url, unpadded, of HMAC-SHA256(key = the claim secret's 32 +// bytes, message = deviceId + "\n" + publicKey), publicKey exactly as sent. +// The reply is the enrollment reply (api.AgentEnrollResponse). The backend +// binds a device with no key, answers the same again for the key it already +// has (so a lost reply is retried safely), and refuses a different key with +// 409. The private key never leaves the board. + +// ErrKeyConflict is a 409: the backend has another key bound to this device. +// It needs a person: a new setup file, after the console resets the device. +var ErrKeyConflict = errors.New("the backend already has a different key for this device") + +// ClaimProof is the claim's proof (see above). +func ClaimProof(secret []byte, deviceID, publicKey string) string { + mac := hmac.New(sha256.New, secret) + mac.Write([]byte(deviceID + "\n" + publicKey)) + return base64.RawURLEncoding.EncodeToString(mac.Sum(nil)) +} + +// ClaimParams is one claim. +type ClaimParams struct { + BackendURL string + DeviceID string + ClaimSecret string // base64url, as in the setup file + Key ed25519.PrivateKey + AgentVersion string + HTTP *http.Client // optional +} + +// Claim sends one claim and returns the backend's reply, checked to be for +// this device and to carry a WebSocket URL. +func Claim(ctx context.Context, p ClaimParams) (*api.AgentEnrollResponse, error) { + secret, err := mbu.DecodeClaimSecret(p.ClaimSecret) + if err != nil { + return nil, err + } + pub := base64.StdEncoding.EncodeToString(p.Key.Public().(ed25519.PublicKey)) + hostname, _ := os.Hostname() + body, err := json.Marshal(map[string]string{ + "deviceId": p.DeviceID, + "publicKey": pub, + "proof": ClaimProof(secret, p.DeviceID, pub), + "agentVersion": p.AgentVersion, + "hostname": hostname, + }) + if err != nil { + return nil, err + } + client := p.HTTP + if client == nil { + client = &http.Client{Timeout: 30 * time.Second} + } + u := strings.TrimRight(p.BackendURL, "/") + "/api/agent/claim" + req, err := http.NewRequestWithContext(ctx, http.MethodPost, u, bytes.NewReader(body)) + if err != nil { + return nil, fmt.Errorf("bad backend URL %q: %w", p.BackendURL, err) + } + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Accept", "application/json") + req.Header.Set("User-Agent", "musallahboard-agent/"+p.AgentVersion) + resp, err := client.Do(req) + if err != nil { + return nil, fmt.Errorf("could not reach %s: %w", u, err) + } + defer resp.Body.Close() + raw, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20)) + if err != nil { + return nil, fmt.Errorf("reading the answer from %s: %w", u, err) + } + switch { + case resp.StatusCode == http.StatusConflict: + return nil, fmt.Errorf("%w (%s)", ErrKeyConflict, message(raw)) + case resp.StatusCode != http.StatusOK: + return nil, fmt.Errorf("%s returned %d: %s", u, resp.StatusCode, message(raw)) + } + var r api.AgentEnrollResponse + if err := json.Unmarshal(raw, &r); err != nil { + return nil, fmt.Errorf("%s did not return the expected JSON: %w", u, err) + } + if r.DeviceId == nil || !strings.EqualFold(r.DeviceId.String(), p.DeviceID) { + return nil, fmt.Errorf("the backend answered the claim for another device (%v)", r.DeviceId) + } + if r.WebsocketUrl == nil || *r.WebsocketUrl == "" { + return nil, errors.New("the backend's claim reply has no websocketUrl") + } + return &r, nil +} + +// message is an error body's {"message"} or its first 300 bytes. +func message(raw []byte) string { + var m struct { + Message string `json:"message"` + } + if json.Unmarshal(raw, &m) == nil && m.Message != "" { + return m.Message + } + return truncate(raw, 300) +} diff --git a/internal/online/enroll/claim_test.go b/internal/online/enroll/claim_test.go new file mode 100644 index 0000000..6114c46 --- /dev/null +++ b/internal/online/enroll/claim_test.go @@ -0,0 +1,83 @@ +package enroll + +import ( + "bytes" + "context" + "crypto/ed25519" + "crypto/hmac" + "encoding/base64" + "encoding/json" + "errors" + "net/http" + "net/http/httptest" + "testing" +) + +// The fixed vector the backend's own test uses (spec C2): device +// 00000000-0000-0000-0000-000000000001, claim secret 32 bytes of 0x01, the +// Ed25519 public key of the seed 32 bytes of 0x02. +const ( + vectorDevice = "00000000-0000-0000-0000-000000000001" + vectorSecret = "AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE" + vectorPub = "gTl3Dqh9F19Wo1Rmw0x+zMuNipG07jeiXfYPW4/Js5Q=" + vectorProof = "2_nUd8LSmcq1kdXUvLW5ZQkAr_yDjiTuIh2AzpJH2sA" +) + +var vectorKey = ed25519.NewKeyFromSeed(bytes.Repeat([]byte{2}, 32)) + +func TestClaimProofVector(t *testing.T) { + if got := base64.StdEncoding.EncodeToString(vectorKey.Public().(ed25519.PublicKey)); got != vectorPub { + t.Fatalf("public key = %s", got) + } + if got := ClaimProof(bytes.Repeat([]byte{1}, 32), vectorDevice, vectorPub); got != vectorProof { + t.Fatalf("proof = %s, want %s", got, vectorProof) + } +} + +func TestClaim(t *testing.T) { + var got map[string]string + status := http.StatusOK + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Method != http.MethodPost || r.URL.Path != "/api/agent/claim" { + http.NotFound(w, r) + return + } + json.NewDecoder(r.Body).Decode(&got) + if status != http.StatusOK { + w.WriteHeader(status) + w.Write([]byte(`{"message":"device already has a different key"}`)) + return + } + json.NewEncoder(w).Encode(map[string]any{ + "deviceId": vectorDevice, "websocketUrl": "wss://api.example.org/api/agent/ws", + "contentSigningKeys": []any{}, + }) + })) + defer srv.Close() + p := ClaimParams{BackendURL: srv.URL + "/", DeviceID: vectorDevice, ClaimSecret: vectorSecret, + Key: vectorKey, AgentVersion: "0.4.0", HTTP: srv.Client()} + + r, err := Claim(context.Background(), p) + if err != nil { + t.Fatal(err) + } + if *r.WebsocketUrl != "wss://api.example.org/api/agent/ws" { + t.Fatalf("reply = %+v", r) + } + if got["deviceId"] != vectorDevice || got["publicKey"] != vectorPub || got["agentVersion"] != "0.4.0" { + t.Fatalf("request = %v", got) + } + // What the backend checks: the proof, compared in constant time. + if !hmac.Equal([]byte(got["proof"]), []byte(vectorProof)) { + t.Fatalf("proof = %s", got["proof"]) + } + + status = http.StatusConflict + if _, err := Claim(context.Background(), p); !errors.Is(err, ErrKeyConflict) { + t.Fatalf("409: err = %v", err) + } + p.ClaimSecret = "short" + if _, err := Claim(context.Background(), p); err == nil { + t.Fatal("a malformed claim secret was sent") + } +} diff --git a/internal/enroll/enroll.go b/internal/online/enroll/enroll.go similarity index 77% rename from internal/enroll/enroll.go rename to internal/online/enroll/enroll.go index 5ed762f..905e164 100644 --- a/internal/enroll/enroll.go +++ b/internal/online/enroll/enroll.go @@ -17,23 +17,21 @@ import ( "fmt" "log/slog" "net/http" - "net/url" "os" - "path/filepath" "strings" "time" - "github.com/LensBridge/agent/internal/api" - "github.com/LensBridge/agent/internal/config" - "github.com/LensBridge/agent/internal/keystore" - "github.com/LensBridge/agent/internal/trust" + "github.com/LensBridge/agent/internal/core/config" + "github.com/LensBridge/agent/internal/core/trust" + "github.com/LensBridge/agent/internal/online/api" + "github.com/LensBridge/agent/internal/online/keystore" ) type Params struct { Token string BackendURL string ConfigPath string - KeyPath string // optional; defaults to config.DefaultKeyPath + KeyPath string // optional; defaults to config.KeyPath // TrustPath is the trust store the backend's content keys are pinned // in; optional, defaults to trust.DefaultPath. TrustPath string @@ -51,7 +49,7 @@ type Params struct { func Run(ctx context.Context, logger *slog.Logger, p Params) error { keyPath := p.KeyPath if keyPath == "" { - keyPath = config.DefaultKeyPath + keyPath = config.KeyPath } // Before anything goes on the wire: the reply pins the content keys and @@ -73,7 +71,7 @@ func Run(ctx context.Context, logger *slog.Logger, p Params) error { hardwareModel := readHardwareModel() // Client and request/response types are generated from the backend's - // openapi.yaml (see internal/api/oapi-codegen.yaml). A field renamed on the + // openapi.yaml (see internal/online/api/oapi-codegen.yaml). A field renamed on the // server now breaks this build instead of silently decoding to a zero value. httpClient := p.HTTPClient if httpClient == nil { @@ -118,11 +116,7 @@ func Run(ctx context.Context, logger *slog.Logger, p Params) error { contentKeys = append(contentKeys, SigningKey{KeyID: k.KeyId, PublicKey: k.PublicKey}) } - // The backend sometimes constructs the WebSocket URL from the HTTP request's - // Host header, which drops the port when behind a reverse proxy or when the - // client connects directly without a Host: port. Patch it back in if the - // backend URL carried an explicit port that the returned WS URL is missing. - websocketURL := restorePort(*enrolled.WebsocketUrl, p.BackendURL) + websocketURL := *enrolled.WebsocketUrl if err := config.CheckWebSocketURL(websocketURL, p.BackendURL, p.InsecureDev); err != nil { // Nothing is saved: the board stays unenrolled. The backend has // consumed the token, so a retry needs a new one once it is fixed. @@ -135,14 +129,23 @@ func Run(ctx context.Context, logger *slog.Logger, p Params) error { if err := keystore.Save(keyPath, priv); err != nil { return fmt.Errorf("save key: %w", err) } - _ = chownToDirOwner(keyPath, filepath.Dir(keyPath)) - cfg := &config.Config{ - DeviceID: deviceID, - BackendURL: strings.TrimRight(p.BackendURL, "/"), - WebSocketURL: websocketURL, - KeyPath: keyPath, + // The board's other settings (a setup file's name, service_port, ...) + // stay; the online identity is the backend's answer. + cfg, err := config.Load(p.ConfigPath) + if err != nil { + cfg = &config.Config{} + } + if cfg.DeviceID != deviceID { + if cfg.DeviceID != "" { + logger.Warn("the backend enrolled this board as a different device than its setup file named", + "setupDeviceId", cfg.DeviceID, "deviceId", deviceID) + } + cfg.DeviceID, cfg.DisplayName, cfg.ProvisionSequence = deviceID, "", 0 } + cfg.BackendURL = strings.TrimRight(p.BackendURL, "/") + cfg.WebSocketURL = websocketURL + cfg.ClaimSecret = "" if p.InsecureDev { on := true cfg.InsecureDevSet = &on @@ -150,11 +153,6 @@ func Run(ctx context.Context, logger *slog.Logger, p Params) error { if err := config.Save(p.ConfigPath, cfg); err != nil { return fmt.Errorf("save config: %w", err) } - _ = chownToDirOwner(p.ConfigPath, filepath.Dir(p.ConfigPath)) - - // The kiosk URL is not written here any more: in v2 the kiosk always - // loads the agent's own local server, and the daemon writes kiosk-url - // itself once it sees the config (docs/architecture.md, section 14). // Pin the backend's content keys. They arrive over the same TLS // connection that just established this device's identity, which is as @@ -217,20 +215,3 @@ func readHardwareModel() string { } return strings.TrimRight(strings.TrimSpace(string(b)), "\x00") } - -// restorePort patches wsURL's host with the port from backendURL when the -// backend omits it — this happens when the backend derives the WebSocket URL -// from the HTTP Host header, which proxies or direct HTTP/1.0 clients may -// omit the port from. -func restorePort(wsURL, backendURL string) string { - ws, err := url.Parse(wsURL) - if err != nil || ws.Port() != "" { - return wsURL // already has a port (or unparseable — leave alone) - } - be, err := url.Parse(backendURL) - if err != nil || be.Port() == "" { - return wsURL // backend URL has no explicit port either — nothing to restore - } - ws.Host = ws.Hostname() + ":" + be.Port() - return ws.String() -} diff --git a/internal/enroll/enroll_test.go b/internal/online/enroll/enroll_test.go similarity index 91% rename from internal/enroll/enroll_test.go rename to internal/online/enroll/enroll_test.go index 3663826..f2bdc2f 100644 --- a/internal/enroll/enroll_test.go +++ b/internal/online/enroll/enroll_test.go @@ -16,8 +16,8 @@ import ( "strings" "testing" - "github.com/LensBridge/agent/internal/config" - "github.com/LensBridge/agent/internal/trust" + "github.com/LensBridge/agent/internal/core/config" + "github.com/LensBridge/agent/internal/core/trust" ) func quietLogger() *slog.Logger { @@ -64,8 +64,6 @@ func TestRunEnrollsAndPersistsConfig(t *testing.T) { t.Fatalf("decode request: %v", err) } w.Header().Set("Content-Type", "application/json") - // Carries an explicit port so restorePort leaves it untouched; the - // port-patching behaviour has its own test below. json.NewEncoder(w).Encode(map[string]any{ "deviceId": deviceID, "websocketUrl": wsURL(server, "wss"), @@ -354,38 +352,6 @@ func assertNothingSaved(t *testing.T, cfgPath, keyPath string) { } } -func TestRestorePort(t *testing.T) { - tests := []struct { - name, wsURL, backendURL, want string - }{ - { - name: "port restored when backend has one and ws does not", - wsURL: "ws://board.example/api/agent/ws", - backendURL: "http://board.example:8080", - want: "ws://board.example:8080/api/agent/ws", - }, - { - name: "existing ws port is left alone", - wsURL: "ws://board.example:9999/api/agent/ws", - backendURL: "http://board.example:8080", - want: "ws://board.example:9999/api/agent/ws", - }, - { - name: "nothing to restore when backend has no port", - wsURL: "ws://board.example/api/agent/ws", - backendURL: "https://board.example", - want: "ws://board.example/api/agent/ws", - }, - } - for _, tc := range tests { - t.Run(tc.name, func(t *testing.T) { - if got := restorePort(tc.wsURL, tc.backendURL); got != tc.want { - t.Errorf("restorePort() = %q, want %q", got, tc.want) - } - }) - } -} - func keys(m map[string]any) []string { out := make([]string, 0, len(m)) for k := range m { diff --git a/internal/enroll/trustkeys.go b/internal/online/enroll/trustkeys.go similarity index 98% rename from internal/enroll/trustkeys.go rename to internal/online/enroll/trustkeys.go index 247b598..40f6fd7 100644 --- a/internal/enroll/trustkeys.go +++ b/internal/online/enroll/trustkeys.go @@ -9,7 +9,7 @@ import ( "strings" "time" - "github.com/LensBridge/agent/internal/trust" + "github.com/LensBridge/agent/internal/core/trust" ) // SigningKey is one content signing key as the backend publishes it, in the diff --git a/internal/keystore/keystore.go b/internal/online/keystore/keystore.go similarity index 81% rename from internal/keystore/keystore.go rename to internal/online/keystore/keystore.go index ef23f21..a623997 100644 --- a/internal/keystore/keystore.go +++ b/internal/online/keystore/keystore.go @@ -1,18 +1,20 @@ // Package keystore manages the per-device Ed25519 private key. // // The key lives at /etc/musallahboard/agent.key as a raw 32-byte seed, mode -// 0600, root-owned. This is symmetric with the backend, which stores the raw -// 32-byte public key in device.public_key. The backend never sees the private -// key — it's generated locally on the Pi at first enroll. +// 0600, owned by the daemon's user (the owner of /etc/musallahboard). The +// backend stores the raw 32-byte public key in device.public_key and never +// sees the private key: it is generated on the board, at its claim or at +// `enroll`. package keystore import ( "crypto/ed25519" "crypto/rand" - "errors" "fmt" "os" "path/filepath" + + "github.com/LensBridge/agent/internal/core/fsutil" ) // SeedSize is the size in bytes of the Ed25519 private-key seed. @@ -58,6 +60,7 @@ func Save(path string, priv ed25519.PrivateKey) error { os.Remove(tmp) return fmt.Errorf("close: %w", err) } + fsutil.ChownToDirOwner(tmp, filepath.Dir(path)) if err := os.Rename(tmp, path); err != nil { os.Remove(tmp) return fmt.Errorf("rename: %w", err) @@ -77,11 +80,3 @@ func Load(path string) (ed25519.PrivateKey, error) { } return ed25519.NewKeyFromSeed(seed), nil } - -// PublicKeyOf returns the 32-byte raw public key for a private key. -func PublicKeyOf(priv ed25519.PrivateKey) (ed25519.PublicKey, error) { - if len(priv) != ed25519.PrivateKeySize { - return nil, errors.New("invalid private key") - } - return priv.Public().(ed25519.PublicKey), nil -} diff --git a/internal/keystore/keystore_test.go b/internal/online/keystore/keystore_test.go similarity index 76% rename from internal/keystore/keystore_test.go rename to internal/online/keystore/keystore_test.go index 8625050..19ca73d 100644 --- a/internal/keystore/keystore_test.go +++ b/internal/online/keystore/keystore_test.go @@ -27,8 +27,7 @@ func TestSaveLoad_RoundTrip(t *testing.T) { if !bytes.Equal(priv.Seed(), loaded.Seed()) { t.Fatalf("seed mismatch after round-trip") } - loadedPub, _ := PublicKeyOf(loaded) - if !bytes.Equal(pub, loadedPub) { + if !bytes.Equal(pub, loaded.Public().(ed25519.PublicKey)) { t.Fatalf("public key mismatch after round-trip") } } @@ -61,17 +60,3 @@ func TestLoad_RejectsWrongSize(t *testing.T) { t.Fatal("expected error for short key, got nil") } } - -func TestPublicKeyOf_MatchesGenerate(t *testing.T) { - pub, priv, _ := Generate() - got, err := PublicKeyOf(priv) - if err != nil { - t.Fatalf("PublicKeyOf: %v", err) - } - if len(got) != ed25519.PublicKeySize { - t.Fatalf("public key size = %d, want %d", len(got), ed25519.PublicKeySize) - } - if !bytes.Equal(pub, got) { - t.Fatalf("public key mismatch") - } -} diff --git a/internal/online/online.go b/internal/online/online.go new file mode 100644 index 0000000..517699c --- /dev/null +++ b/internal/online/online.go @@ -0,0 +1,375 @@ +// Package online is the board's optional fleet layer (docs/architecture.md, +// section 9): content sync and weather from the LensBridge backend, and the +// backend WebSocket with telemetry and remote commands. +// +// It runs only on a board whose agent.toml names a device and a backend, and +// whose device key is bound to it (by `enroll`, or by the claim a setup file +// starts). Everything it does goes through the core: packages through the +// importer, the status through the local server. Nothing in the core depends +// on it, and a board without it loses no board function. +package online + +import ( + "context" + "crypto/ed25519" + "encoding/json" + "errors" + "fmt" + "io/fs" + "log/slog" + "math/rand" + "net/http" + "sync" + "time" + + "github.com/LensBridge/agent/internal/core/config" + "github.com/LensBridge/agent/internal/core/importer" + "github.com/LensBridge/agent/internal/core/kiosk" + "github.com/LensBridge/agent/internal/core/store" + "github.com/LensBridge/agent/internal/core/trust" + "github.com/LensBridge/agent/internal/core/updates" + "github.com/LensBridge/agent/internal/online/api" + "github.com/LensBridge/agent/internal/online/boardsync" + "github.com/LensBridge/agent/internal/online/commands" + "github.com/LensBridge/agent/internal/online/enroll" + "github.com/LensBridge/agent/internal/online/keystore" + "github.com/LensBridge/agent/internal/online/wsclient" +) + +// Deps is what the online layer needs from the board. +type Deps struct { + Config *config.Live + // KeyPath is the device key; config.KeyPath on a board. + KeyPath string + Layout store.Layout + Importer *importer.Importer + Updates *updates.Scheduler + Kiosk *kiosk.Client + // BoardReport is what every heartbeat says about the board. + BoardReport func() any + AgentVersion string + Logger *slog.Logger + // TrustPath is trust.json, to say whether the backend's content keys + // are pinned; trust.DefaultPath on a board. + TrustPath string + // HTTP is optional (tests). + HTTP *http.Client + // ClaimRetry is the first wait after a failed claim; zero is + // ClaimRetry (tests shorten it). + ClaimRetry time.Duration +} + +// Claim retry: a board set up for a backend it cannot reach yet (no network +// until someone plugs one in) keeps trying, without ever blocking the board. +const ( + ClaimRetry = time.Minute + ClaimRetryMax = time.Hour +) + +// Layer runs the online layer for whatever agent.toml says, and reports its +// state to the local status. +type Layer struct { + d Deps + + mu sync.Mutex + syncer *boardsync.Syncer + ws *wsclient.Client + // why is the reason the layer is configured but not running, or "". + why string + // on is whether agent.toml asks for the layer at all. + on, contentSync bool +} + +// New returns a Layer. Call Run to start it. +func New(d Deps) *Layer { + if d.Logger == nil { + d.Logger = slog.New(slog.DiscardHandler) + } + if d.KeyPath == "" { + d.KeyPath = config.KeyPath + } + if d.TrustPath == "" { + d.TrustPath = trust.DefaultPath + } + if d.ClaimRetry == 0 { + d.ClaimRetry = ClaimRetry + } + return &Layer{d: d} +} + +// settings is the part of agent.toml the online layer is built from; a +// change to it restarts the layer. +type settings struct { + deviceID, backendURL, websocketURL, claimSecret string + insecureDev, contentSync bool +} + +func settingsOf(c *config.Config) settings { + return settings{c.DeviceID, c.BackendURL, c.WebSocketURL, c.ClaimSecret, c.InsecureDev(), c.ContentSync()} +} + +// Run runs the layer until ctx ends, starting it over whenever its part of +// agent.toml changes (a setup file applied, a claim completed). +func (l *Layer) Run(ctx context.Context) { + for { + changed := l.d.Config.Changed() + cfg := l.d.Config.Get() + runCtx, cancel := context.WithCancel(ctx) + done := make(chan struct{}) + go func() { + defer close(done) + l.runOnce(runCtx, cfg) + }() + restart := false + for !restart { + select { + case <-ctx.Done(): + cancel() + <-done + return + case <-changed: + changed = l.d.Config.Changed() + restart = settingsOf(l.d.Config.Get()) != settingsOf(cfg) + } + } + l.d.Logger.Info("online settings changed; restarting the online layer") + cancel() + <-done + } +} + +// runOnce runs the layer for cfg until ctx ends or it cannot run. +func (l *Layer) runOnce(ctx context.Context, cfg *config.Config) { + l.set(nil, nil, cfg.Online(), cfg.ContentSync(), "") + if !cfg.Online() { + return + } + if cfg.WebSocketURL == "" { + if cfg.ClaimSecret == "" { + l.set(nil, nil, true, cfg.ContentSync(), "not enrolled: no device key is bound to this board yet") + return + } + // Once the claim is saved, Run starts the layer over with it. + l.claim(ctx, cfg) + return + } + priv, err := keystore.Load(l.d.KeyPath) + if err != nil { + l.d.Logger.Error("device key unreadable: no sync, no remote commands", "err", err, "keyPath", l.d.KeyPath) + l.set(nil, nil, true, cfg.ContentSync(), "device key unreadable") + return + } + if err := checkTransport(l.d.Logger, cfg); err != nil { + l.set(nil, nil, true, cfg.ContentSync(), "not talking to LensBridge: "+err.Error()) + return + } + l.serve(ctx, cfg, priv) +} + +// claim binds the device key (made here if the board has none; it never +// leaves the board) to the device named in agent.toml, with the setup file's +// claim secret, retrying with backoff until it works or ctx ends. On success +// it saves the WebSocket URL and drops the secret. +func (l *Layer) claim(ctx context.Context, cfg *config.Config) { + log := l.d.Logger.With("backendUrl", cfg.BackendURL, "deviceId", cfg.DeviceID) + why := func(s string) { l.set(nil, nil, true, cfg.ContentSync(), s) } + // The reply decides where the board takes commands from, so it must + // come over TLS. + if err := config.CheckBackendURL(cfg.BackendURL, cfg.InsecureDev()); err != nil { + log.Error("not claiming: the setup file's backend is not safe to use", "err", err) + why("not talking to LensBridge: " + err.Error()) + return + } + priv, err := deviceKey(l.d.KeyPath) + if err != nil { + log.Error("no device key: cannot claim", "err", err, "keyPath", l.d.KeyPath) + why("device key unreadable") + return + } + wait := l.d.ClaimRetry + why("claiming this board at " + cfg.BackendURL) + for { + err := l.claimOnce(ctx, cfg, priv) + if err == nil || ctx.Err() != nil { + return + } + if errors.Is(err, enroll.ErrKeyConflict) { + log.Error("claim refused: LensBridge has a different key for this board. Reset it in the console and use a new setup file", "err", err) + wait = ClaimRetryMax + } else { + log.Warn("claim failed; retrying", "err", err, "retryIn", wait) + } + why("claim failed: " + err.Error()) + t := time.NewTimer(wait + time.Duration(rand.Int63n(int64(wait/4)+1))) + select { + case <-ctx.Done(): + t.Stop() + return + case <-t.C: + } + wait = min(wait*2, ClaimRetryMax) + } +} + +func (l *Layer) claimOnce(ctx context.Context, cfg *config.Config, priv ed25519.PrivateKey) error { + r, err := enroll.Claim(ctx, enroll.ClaimParams{ + BackendURL: cfg.BackendURL, DeviceID: cfg.DeviceID, ClaimSecret: cfg.ClaimSecret, + Key: priv, AgentVersion: l.d.AgentVersion, HTTP: l.d.HTTP, + }) + if err != nil { + return err + } + ws := *r.WebsocketUrl + if err := config.CheckWebSocketURL(ws, cfg.BackendURL, cfg.InsecureDev()); err != nil { + return fmt.Errorf("the backend's reply cannot be used: %w", err) + } + l.checkPinned(r.ContentSigningKeys) + err = l.d.Config.Update(func(c *config.Config) error { + if settingsOf(c) != settingsOf(cfg) { + return errors.New("agent.toml changed during the claim") + } + c.WebSocketURL, c.ClaimSecret = ws, "" + return nil + }) + if err != nil { + return err + } + l.d.Logger.Info("board claimed: its device key is bound in LensBridge", "deviceId", cfg.DeviceID, "websocketUrl", ws) + return nil +} + +// checkPinned says when the backend signs content with a key this board does +// not trust. The daemon cannot pin keys (trust.json is root's); setup.sh +// pins the content key, and `trust fetch` re-reads the backend's. +func (l *Layer) checkPinned(keys []api.SigningKeyView) { + ring, err := trust.LoadRing(l.d.TrustPath) + if err != nil { + return + } + pinned := ring.Keys(trust.RoleContent) + for _, k := range keys { + if _, ok := pinned[k.KeyId]; !ok { + l.d.Logger.Warn("LensBridge signs content with a key this board does not trust; its content will be refused until it is pinned: sudo musallahboard-agent trust fetch", + "keyId", k.KeyId) + } + } +} + +// deviceKey loads the device key, or makes and saves one if there is none. +// It is saved before it is first sent, so every retry claims the same key. +func deviceKey(path string) (ed25519.PrivateKey, error) { + priv, err := keystore.Load(path) + if err == nil || !errors.Is(err, fs.ErrNotExist) { + return priv, err + } + _, priv, err = keystore.Generate() + if err != nil { + return nil, err + } + if err := keystore.Save(path, priv); err != nil { + return nil, err + } + return priv, nil +} + +// serve runs content sync and the backend WebSocket until ctx ends. +func (l *Layer) serve(ctx context.Context, cfg *config.Config, priv []byte) { + log := l.d.Logger + syncer := boardsync.New(boardsync.Deps{ + Cfg: cfg, Key: priv, Layout: l.d.Layout, Importer: l.d.Importer, + AgentVersion: l.d.AgentVersion, Logger: log, HTTP: l.d.HTTP, + }) + ws := wsclient.New(cfg, priv, log, l.d.AgentVersion) + ws.SetPageProber(l.d.Kiosk) + ws.SetBoardReport(l.d.BoardReport) + ws.SetContentChanged(syncer.Trigger) + registry := commands.NewRegistry() + registry.Register(&commands.ChromeReload{CDP: l.d.Kiosk}) + registry.Register(&commands.ChromeScreenshot{CDP: l.d.Kiosk}) + registry.Register(&commands.ConfigRefresh{CDP: l.d.Kiosk, Before: syncer.Trigger}) + registry.Register(&commands.KioskRestart{}) + registry.Register(&commands.SystemReboot{}) + registry.Register(&commands.LogsTail{}) + registry.Register(&commands.UpdateInstallNow{Run: l.d.Updates.CheckAndInstall}) + log.Info("command handlers registered", "kinds", registry.Kinds()) + ws.SetCommandHandler(commands.NewDispatcher(registry, log).Handle) + + l.set(syncer, ws, true, cfg.ContentSync(), "") + var wg sync.WaitGroup + wg.Add(2) + go func() { defer wg.Done(); syncer.Run(ctx) }() + go func() { defer wg.Done(); ws.Run(ctx) }() + wg.Wait() + l.set(nil, nil, true, cfg.ContentSync(), "") +} + +func (l *Layer) set(s *boardsync.Syncer, ws *wsclient.Client, on, contentSync bool, why string) { + l.mu.Lock() + defer l.mu.Unlock() + l.syncer, l.ws, l.on, l.contentSync, l.why = s, ws, on, contentSync, why +} + +// Sync is the "sync" object of /api/local/status. +func (l *Layer) Sync() any { + l.mu.Lock() + defer l.mu.Unlock() + switch { + case l.syncer != nil: + return l.syncer.Status() + case l.why != "": + // Enabled as configured, so the board app and `status` show the + // reason as a sync error rather than "sync off". + return map[string]any{"enabled": l.contentSync, "lastError": l.why} + } + return boardsync.Status{Enabled: false} +} + +// Weather is the live weather overlay, if there is one. +func (l *Layer) Weather() (json.RawMessage, bool) { + l.mu.Lock() + s := l.syncer + l.mu.Unlock() + if s == nil { + return nil, false + } + return s.Weather() +} + +// Backend is the "backend" object of /api/local/status: the WebSocket's +// state, why there is none, or nil on a board without the online layer. +func (l *Layer) Backend() any { + l.mu.Lock() + defer l.mu.Unlock() + switch { + case l.ws != nil: + s := l.ws.State() + return &s + case l.why != "": + return map[string]any{"connected": false, "lastError": l.why} + } + return nil +} + +// checkTransport checks that the config may be used to talk to the backend +// (config.CheckTransport) and says so loudly at every start when it may not, +// or when it may only because of the insecure_dev opt-in. A board enrolled +// over plain http before https was required lands here: it keeps showing what +// it has, and the log, `musallahboard-agent status` and the board app's sync +// error all carry the reason and the fix. +func checkTransport(logger *slog.Logger, cfg *config.Config) error { + if err := cfg.CheckTransport(); err != nil { + logger.Error("REFUSING TO TALK TO THE BACKEND: this board's config is not safe to use. "+ + "Serving installed content only: no content sync, no remote commands. "+ + "Re-enroll it over https (sudo musallahboard-agent enroll --force --token=... --backend=https://...), "+ + "or, for a development board only, add insecure_dev = true to "+config.DefaultPath+" and restart the agent.", + "err", err, "backendUrl", cfg.BackendURL, "websocketUrl", cfg.WebSocketURL) + return err + } + if cfg.InsecureDev() { + logger.Warn("INSECURE DEVELOPMENT BOARD: insecure_dev = true, so this board accepts a plaintext backend. "+ + "Anyone on its network can impersonate the backend: send it content, reboot it, read its screen and logs. "+ + "Never deploy a board like this.", + "backendUrl", cfg.BackendURL, "websocketUrl", cfg.WebSocketURL) + } + return nil +} diff --git a/internal/online/online_test.go b/internal/online/online_test.go new file mode 100644 index 0000000..d5aa9ca --- /dev/null +++ b/internal/online/online_test.go @@ -0,0 +1,138 @@ +package online + +import ( + "bytes" + "context" + "encoding/base64" + "encoding/json" + "log/slog" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "strings" + "sync" + "testing" + "time" + + "github.com/LensBridge/agent/internal/core/config" + "github.com/LensBridge/agent/internal/core/kiosk" + "github.com/LensBridge/agent/internal/core/store" + "github.com/LensBridge/agent/internal/online/wsclient" +) + +const testDevice = "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b" + +func TestCheckTransport(t *testing.T) { + on := true + cases := []struct { + name string + cfg config.Config + wantErr bool + wantLog string + }{ + {"tls", config.Config{BackendURL: "https://api.example.com", WebSocketURL: "wss://api.example.com/ws"}, false, ""}, + {"http without opt-in", config.Config{BackendURL: "http://10.0.2.2:8080", WebSocketURL: "ws://10.0.2.2:8080/ws"}, true, "REFUSING TO TALK TO THE BACKEND"}, + {"socket elsewhere", config.Config{BackendURL: "https://api.example.com", WebSocketURL: "wss://other.example.com/ws"}, true, "REFUSING TO TALK TO THE BACKEND"}, + {"insecure dev", config.Config{BackendURL: "http://10.0.2.2:8080", WebSocketURL: "ws://10.0.2.2:8080/ws", InsecureDevSet: &on}, false, "INSECURE DEVELOPMENT BOARD"}, + {"insecure dev with tls still warns", config.Config{BackendURL: "https://api.example.com", WebSocketURL: "wss://api.example.com/ws", InsecureDevSet: &on}, false, "INSECURE DEVELOPMENT BOARD"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + var buf bytes.Buffer + err := checkTransport(slog.New(slog.NewTextHandler(&buf, nil)), &tc.cfg) + if (err != nil) != tc.wantErr { + t.Errorf("err = %v, want error %v", err, tc.wantErr) + } + if tc.wantLog == "" && buf.Len() != 0 { + t.Errorf("unexpected log: %s", buf.String()) + } + if tc.wantLog != "" && !strings.Contains(buf.String(), tc.wantLog) { + t.Errorf("log %q does not say %q", buf.String(), tc.wantLog) + } + }) + } +} + +// A board set up with a backend claims its key (retrying while the backend +// is not answering, with the same key), saves the WebSocket URL, drops the +// claim secret, and the layer starts over online. +func TestLayerClaims(t *testing.T) { + var claims []map[string]string + var mu sync.Mutex + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path != "/api/agent/claim" { + http.NotFound(w, r) + return + } + var body map[string]string + json.NewDecoder(r.Body).Decode(&body) + mu.Lock() + claims = append(claims, body) + n := len(claims) + mu.Unlock() + if n == 1 { + http.Error(w, "starting", http.StatusServiceUnavailable) + return + } + json.NewEncoder(w).Encode(map[string]any{"deviceId": testDevice, + "websocketUrl": "ws://" + r.Host + "/api/agent/ws", "contentSigningKeys": []any{}}) + })) + defer srv.Close() + + dir := t.TempDir() + on := true + path := filepath.Join(dir, "agent.toml") + secret := base64.RawURLEncoding.EncodeToString(bytes.Repeat([]byte{1}, 32)) + if err := config.Save(path, &config.Config{DeviceID: testDevice, BackendURL: srv.URL, ClaimSecret: secret, InsecureDevSet: &on}); err != nil { + t.Fatal(err) + } + live, _ := config.Open(path) + l := New(Deps{Config: live, KeyPath: filepath.Join(dir, "agent.key"), TrustPath: filepath.Join(dir, "trust.json"), + Layout: store.Layout{Root: dir}, Kiosk: kiosk.NewClient("http://127.0.0.1:1"), + BoardReport: func() any { return nil }, AgentVersion: "0.4.0", HTTP: srv.Client(), + ClaimRetry: 10 * time.Millisecond}) + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + done := make(chan struct{}) + go func() { l.Run(ctx); close(done) }() + for live.Get().WebSocketURL == "" && ctx.Err() == nil { + time.Sleep(5 * time.Millisecond) + } + // The layer starts over with the saved URL: now it is "connecting". + for { + if _, ok := l.Backend().(*wsclient.ConnState); ok { + break + } + if ctx.Err() != nil { + t.Fatalf("layer did not start online: %#v", l.Backend()) + } + time.Sleep(5 * time.Millisecond) + } + cancel() + <-done + + saved, _ := config.Load(path) + if saved.WebSocketURL == "" || saved.ClaimSecret != "" { + t.Fatalf("saved config = %+v", saved) + } + mu.Lock() + defer mu.Unlock() + if len(claims) < 2 || claims[0]["publicKey"] != claims[1]["publicKey"] { + t.Fatalf("claims = %v", claims) + } + if _, err := os.Stat(filepath.Join(dir, "agent.key")); err != nil { + t.Fatal("device key not saved") + } +} + +// An offline board (no backend) has no online layer, and says nothing. +func TestLayerOffline(t *testing.T) { + l := New(Deps{Config: config.InMemory(config.Config{DeviceID: testDevice})}) + ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond) + defer cancel() + l.Run(ctx) + if l.Backend() != nil { + t.Fatalf("backend = %v", l.Backend()) + } +} diff --git a/internal/wsclient/frames.go b/internal/online/wsclient/frames.go similarity index 80% rename from internal/wsclient/frames.go rename to internal/online/wsclient/frames.go index c97a647..8c19545 100644 --- a/internal/wsclient/frames.go +++ b/internal/online/wsclient/frames.go @@ -1,10 +1,6 @@ package wsclient -import ( - "encoding/json" - - "github.com/LensBridge/agent/internal/telemetry" -) +import "encoding/json" // IncomingFrame is the union of every frame the backend sends. Fields are all // optional except {type, seq, sessionId} — which type is in play is decided by @@ -110,37 +106,3 @@ type CommandResultFrame struct { ErrorMessage string `json:"errorMessage,omitempty"` DurationMs *int64 `json:"durationMs,omitempty"` } - -// TelemetryFromSnapshot adapts the local telemetry.Snapshot (long-lived) into -// the wire shape the backend expects. Zero-ish values become nils so the -// backend stores them as NULL rather than misleading zeroes. -func TelemetryFromSnapshot(s telemetry.Snapshot) Telemetry { - t := Telemetry{ - ThrottleFlags: s.ThrottleFlags, - IPv4: s.IPAddrs, - WifiSSID: s.SSID, - AgentVersion: s.AgentVersion, - DisplayedFrameKey: s.DisplayedFrameKey, - } - if s.UptimeSec > 0 { - v := s.UptimeSec - t.UptimeSec = &v - } - if s.CPUTempC > 0 { - v := s.CPUTempC - t.CPUTempC = &v - } - if s.MemTotalMB > 0 { - used := int(s.MemUsedMB) - total := int(s.MemTotalMB) - t.MemUsedMb = &used - t.MemTotalMb = &total - } - if s.DiskUsedPct > 0 { - v := int(s.DiskUsedPct + 0.5) // round to nearest percent - t.DiskUsedPct = &v - } - alive := s.KioskAlive - t.KioskAlive = &alive - return t -} diff --git a/internal/wsclient/frames_test.go b/internal/online/wsclient/frames_test.go similarity index 60% rename from internal/wsclient/frames_test.go rename to internal/online/wsclient/frames_test.go index c20f4b6..28db0fb 100644 --- a/internal/wsclient/frames_test.go +++ b/internal/online/wsclient/frames_test.go @@ -3,29 +3,28 @@ package wsclient import ( "encoding/json" "testing" - - "github.com/LensBridge/agent/internal/telemetry" ) // The wire names here are a contract with the backend's HeartbeatFrame.Telemetry. // Renaming a field without renaming it there means the value is silently dropped, // which is how agentVersion went missing for the entire fleet. -func TestTelemetryFromSnapshotWireNames(t *testing.T) { - snap := telemetry.Snapshot{ - UptimeSec: 3600, - CPUTempC: 51.5, +func TestTelemetryWireNames(t *testing.T) { + up, temp, used, total, disk, alive := int64(3600), 51.5, 512, 2048, 42, true + tel := Telemetry{ + UptimeSec: &up, + CPUTempC: &temp, ThrottleFlags: "0x0", - MemUsedMB: 512, - MemTotalMB: 2048, - DiskUsedPct: 41.6, - KioskAlive: true, + MemUsedMb: &used, + MemTotalMb: &total, + DiskUsedPct: &disk, + KioskAlive: &alive, DisplayedFrameKey: "poster-3", - IPAddrs: []string{"10.0.0.7"}, - SSID: "MSA-WIFI", + IPv4: []string{"10.0.0.7"}, + WifiSSID: "MSA-WIFI", AgentVersion: "1.2.3", } - raw, err := json.Marshal(TelemetryFromSnapshot(snap)) + raw, err := json.Marshal(tel) if err != nil { t.Fatalf("marshal: %v", err) } @@ -40,7 +39,7 @@ func TestTelemetryFromSnapshotWireNames(t *testing.T) { "throttleFlags": "0x0", "memUsedMb": float64(512), "memTotalMb": float64(2048), - "diskUsedPct": float64(42), // rounded to nearest percent + "diskUsedPct": float64(42), "kioskAlive": true, "displayedFrameKey": "poster-3", "wifiSsid": "MSA-WIFI", @@ -56,18 +55,10 @@ func TestTelemetryFromSnapshotWireNames(t *testing.T) { } } -// The frame key is a kiosk slide key, never a UUID. Asserting a value the -// backend could not parse as one keeps that explicit. -func TestTelemetryFrameKeyIsNotAUUID(t *testing.T) { - tel := TelemetryFromSnapshot(telemetry.Snapshot{DisplayedFrameKey: "next-prayer"}) - if tel.DisplayedFrameKey != "next-prayer" { - t.Fatalf("DisplayedFrameKey = %q", tel.DisplayedFrameKey) - } -} - // Missing readings must serialize as absent, not as a misleading zero. -func TestTelemetryFromSnapshotOmitsUnreadValues(t *testing.T) { - raw, err := json.Marshal(TelemetryFromSnapshot(telemetry.Snapshot{})) +func TestTelemetryOmitsUnreadValues(t *testing.T) { + dead := false + raw, err := json.Marshal(Telemetry{KioskAlive: &dead}) if err != nil { t.Fatalf("marshal: %v", err) } @@ -82,8 +73,6 @@ func TestTelemetryFromSnapshotOmitsUnreadValues(t *testing.T) { t.Errorf("%s should be omitted when unread, got %v", absent, got[absent]) } } - // kioskAlive is always sent: "we could not tell" and "the board is down" - // must not look the same to the fleet dashboard. if got["kioskAlive"] != false { t.Errorf("kioskAlive = %v, want false", got["kioskAlive"]) } diff --git a/internal/wsclient/handshake.go b/internal/online/wsclient/handshake.go similarity index 100% rename from internal/wsclient/handshake.go rename to internal/online/wsclient/handshake.go diff --git a/internal/wsclient/handshake_test.go b/internal/online/wsclient/handshake_test.go similarity index 100% rename from internal/wsclient/handshake_test.go rename to internal/online/wsclient/handshake_test.go diff --git a/internal/wsclient/session.go b/internal/online/wsclient/session.go similarity index 100% rename from internal/wsclient/session.go rename to internal/online/wsclient/session.go diff --git a/internal/telemetry/telemetry.go b/internal/online/wsclient/telemetry.go similarity index 64% rename from internal/telemetry/telemetry.go rename to internal/online/wsclient/telemetry.go index 86e57cd..85e0ac6 100644 --- a/internal/telemetry/telemetry.go +++ b/internal/online/wsclient/telemetry.go @@ -1,4 +1,4 @@ -package telemetry +package wsclient import ( "bufio" @@ -11,59 +11,50 @@ import ( "strings" "time" - "github.com/LensBridge/agent/internal/cdp" - "github.com/LensBridge/agent/internal/netinfo" + "github.com/LensBridge/agent/internal/core/kiosk" + "github.com/LensBridge/agent/internal/core/netinfo" ) -// Snapshot is one heartbeat payload's worth of telemetry. Optional fields -// (any with omitempty) may be missing if the underlying source isn't -// available — collecting telemetry must never fail; degraded data is fine. -type Snapshot struct { - Timestamp int64 `json:"timestamp"` - UptimeSec int64 `json:"uptimeSec"` - CPUTempC float64 `json:"cpuTempC,omitempty"` - ThrottleFlags string `json:"throttleFlags,omitempty"` - MemUsedMB int64 `json:"memUsedMb"` - MemTotalMB int64 `json:"memTotalMb"` - DiskUsedPct float64 `json:"diskUsedPct,omitempty"` - KioskAlive bool `json:"kioskAlive"` - DisplayedFrameKey string `json:"displayedFrameKey,omitempty"` - IPAddrs []string `json:"ipAddrs,omitempty"` - SSID string `json:"ssid,omitempty"` - AgentVersion string `json:"agentVersion"` - SafeMode bool `json:"safeMode,omitempty"` -} - // PageProber reports what the kiosk browser is currently showing. Satisfied by -// *cdp.Client; pass nil to skip the browser probe entirely. +// *kiosk.Client; pass nil to skip the browser probe entirely. type PageProber interface { - PageStatus(ctx context.Context) (cdp.PageStatus, error) + PageStatus(ctx context.Context) (kiosk.PageStatus, error) } // pageProbeTimeout bounds the CDP round trip. Chromium is on loopback, so this // is generous; the point is that a wedged browser must never stall a heartbeat. const pageProbeTimeout = 3 * time.Second -// Collect gathers a fresh snapshot. Errors in individual collectors are -// swallowed and the corresponding field left zero/empty. -func Collect(ctx context.Context, agentVersion string, safeMode bool, prober PageProber) Snapshot { - s := Snapshot{ - Timestamp: time.Now().Unix(), - AgentVersion: agentVersion, - SafeMode: safeMode, - } - s.UptimeSec, _ = readUptime() - s.CPUTempC, _ = readCPUTemp() - s.ThrottleFlags, _ = readThrottleFlags(ctx) - s.MemUsedMB, s.MemTotalMB, _ = readMemInfo() - s.DiskUsedPct, _ = readDiskUsedPct() - s.KioskAlive, s.DisplayedFrameKey = checkKiosk(ctx, prober) - // Unfiltered on purpose: the heartbeat reports every address the box holds, - // link-local included, so the backend can see a board that failed DHCP. - // The enrollment splash uses netinfo.Collect, which drops those. - s.IPAddrs = netinfo.IPv4Addrs() - s.SSID, _ = netinfo.SSID(ctx) - return s +// collectTelemetry gathers one heartbeat's telemetry. It never fails: a +// reading that cannot be taken is left out (nil, so the backend stores NULL +// rather than a misleading zero). +func collectTelemetry(ctx context.Context, agentVersion string, prober PageProber) Telemetry { + t := Telemetry{AgentVersion: agentVersion} + if v, err := readUptime(); err == nil && v > 0 { + t.UptimeSec = &v + } + if v, err := readCPUTemp(); err == nil && v > 0 { + t.CPUTempC = &v + } + t.ThrottleFlags, _ = readThrottleFlags(ctx) + if used, total, err := readMemInfo(); err == nil && total > 0 { + u, tot := int(used), int(total) + t.MemUsedMb, t.MemTotalMb = &u, &tot + } + if v, err := readDiskUsedPct(); err == nil && v > 0 { + pct := int(v + 0.5) // nearest percent + t.DiskUsedPct = &pct + } + // kioskAlive is always sent: "could not tell" and "the board is down" + // must not look the same to the fleet dashboard. + alive, frame := checkKiosk(ctx, prober) + t.KioskAlive, t.DisplayedFrameKey = &alive, frame + // Unfiltered on purpose: the heartbeat reports every address the box + // holds, link-local included, so the backend can see a board that + // failed DHCP. + t.IPv4 = netinfo.IPv4Addrs() + t.WifiSSID, _ = netinfo.SSID(ctx) + return t } func readUptime() (int64, error) { @@ -162,7 +153,7 @@ func readDiskUsedPct() (float64, error) { // // The systemd unit is Restart=always, so `is-active` says "active" almost // unconditionally — including while Chromium is crash-looping, parked on the -// enrollment splash, or showing a crashed tab ("Aw, Snap!"). Ask the browser +// setup screen, or showing a crashed tab ("Aw, Snap!"). Ask the browser // instead, and fall back to the unit state only when there is no browser to // ask (no CDP port, browser still starting, or a build without // --remote-debugging-port). @@ -180,14 +171,14 @@ func checkKiosk(ctx context.Context, prober PageProber) (alive bool, frameID str case err == nil: // The board answered. It's alive by definition. return true, status.SlideKey - case errors.Is(err, cdp.ErrEvalUndefined), - errors.Is(err, cdp.ErrPageThrew), - errors.Is(err, cdp.ErrPageNavigating): + case errors.Is(err, kiosk.ErrEvalUndefined), + errors.Is(err, kiosk.ErrPageThrew), + errors.Is(err, kiosk.ErrPageNavigating): // A page answered (or is between documents) but isn't the board: - // the splash, the update screen, a frontend too old to expose + // the setup screen, the update screen, a frontend too old to expose // getStatus(), or a reload in flight. The browser is up. return true, "" - case errors.Is(err, cdp.ErrPageCrashed), errors.Is(err, cdp.ErrPageUnresponsive): + case errors.Is(err, kiosk.ErrPageCrashed), errors.Is(err, kiosk.ErrPageUnresponsive): // The browser is there and its page is dead. return false, "" } diff --git a/internal/telemetry/disk_linux.go b/internal/online/wsclient/telemetry_disk_linux.go similarity index 94% rename from internal/telemetry/disk_linux.go rename to internal/online/wsclient/telemetry_disk_linux.go index be8cec3..94cb094 100644 --- a/internal/telemetry/disk_linux.go +++ b/internal/online/wsclient/telemetry_disk_linux.go @@ -1,6 +1,6 @@ //go:build linux -package telemetry +package wsclient import "syscall" diff --git a/internal/telemetry/disk_other.go b/internal/online/wsclient/telemetry_disk_other.go similarity index 93% rename from internal/telemetry/disk_other.go rename to internal/online/wsclient/telemetry_disk_other.go index 4fa47df..55b11be 100644 --- a/internal/telemetry/disk_other.go +++ b/internal/online/wsclient/telemetry_disk_other.go @@ -1,6 +1,6 @@ //go:build !linux -package telemetry +package wsclient // Stub for non-Linux dev environments (Windows/macOS) so the package // compiles. Pi builds use disk_linux.go via build tag. diff --git a/internal/telemetry/kiosk_test.go b/internal/online/wsclient/telemetry_test.go similarity index 80% rename from internal/telemetry/kiosk_test.go rename to internal/online/wsclient/telemetry_test.go index 60fca61..b9b7071 100644 --- a/internal/telemetry/kiosk_test.go +++ b/internal/online/wsclient/telemetry_test.go @@ -1,4 +1,4 @@ -package telemetry +package wsclient import ( "context" @@ -6,16 +6,16 @@ import ( "fmt" "testing" - "github.com/LensBridge/agent/internal/cdp" + "github.com/LensBridge/agent/internal/core/kiosk" ) type stubProber struct { - status cdp.PageStatus + status kiosk.PageStatus err error calls int } -func (s *stubProber) PageStatus(context.Context) (cdp.PageStatus, error) { +func (s *stubProber) PageStatus(context.Context) (kiosk.PageStatus, error) { s.calls++ return s.status, s.err } @@ -23,7 +23,7 @@ func (s *stubProber) PageStatus(context.Context) (cdp.PageStatus, error) { // The board answering is the only positive proof the kiosk is really up, and // it is also where displayedFrameKey comes from. func TestCheckKioskBoardAnswers(t *testing.T) { - p := &stubProber{status: cdp.PageStatus{Paired: true, SlideKey: "poster-3"}} + p := &stubProber{status: kiosk.PageStatus{Paired: true, SlideKey: "poster-3"}} alive, frame := checkKiosk(context.Background(), p) @@ -35,10 +35,10 @@ func TestCheckKioskBoardAnswers(t *testing.T) { } } -// The enrollment splash (and any frontend older than getStatus) has no hook. +// The setup screen (and any frontend older than getStatus) has no hook. // Chromium is still up, so the kiosk is alive — just not showing a frame. func TestCheckKioskSplashIsStillAlive(t *testing.T) { - p := &stubProber{err: cdp.ErrEvalUndefined} + p := &stubProber{err: kiosk.ErrEvalUndefined} alive, frame := checkKiosk(context.Background(), p) @@ -80,8 +80,8 @@ func TestCheckKioskNilProber(t *testing.T) { // must not be consulted: the board is blank and has to be reported as such. func TestCheckKioskDeadPageIsNotAlive(t *testing.T) { for _, err := range []error{ - fmt.Errorf("%w (http://127.0.0.1:8080/)", cdp.ErrPageCrashed), - fmt.Errorf("%w: read: context deadline exceeded", cdp.ErrPageUnresponsive), + fmt.Errorf("%w (http://127.0.0.1:8080/)", kiosk.ErrPageCrashed), + fmt.Errorf("%w: read: context deadline exceeded", kiosk.ErrPageUnresponsive), } { p := &stubProber{err: err} alive, frame := checkKiosk(context.Background(), p) @@ -97,8 +97,8 @@ func TestCheckKioskDeadPageIsNotAlive(t *testing.T) { // A page between documents, or one whose hook threw, still answered. func TestCheckKioskTransientPageStatesAreAlive(t *testing.T) { for _, err := range []error{ - fmt.Errorf("%w: Execution context was destroyed.", cdp.ErrPageNavigating), - fmt.Errorf("%w: TypeError: x is undefined", cdp.ErrPageThrew), + fmt.Errorf("%w: Execution context was destroyed.", kiosk.ErrPageNavigating), + fmt.Errorf("%w: TypeError: x is undefined", kiosk.ErrPageThrew), } { p := &stubProber{err: err} if alive, _ := checkKiosk(context.Background(), p); !alive { @@ -112,8 +112,8 @@ func TestCheckKioskTransientPageStatesAreAlive(t *testing.T) { func TestCheckKioskUnreachableUsesUnitState(t *testing.T) { want := systemdKioskActive(context.Background()) for _, err := range []error{ - fmt.Errorf("%w at http://localhost:9222: connection refused", cdp.ErrDebuggerUnreachable), - fmt.Errorf("%w (0 total)", cdp.ErrNoPageTarget), + fmt.Errorf("%w at http://localhost:9222: connection refused", kiosk.ErrDebuggerUnreachable), + fmt.Errorf("%w (0 total)", kiosk.ErrNoPageTarget), } { p := &stubProber{err: err} if alive, _ := checkKiosk(context.Background(), p); alive != want { diff --git a/internal/online/wsclient/transport_test.go b/internal/online/wsclient/transport_test.go new file mode 100644 index 0000000..24a4759 --- /dev/null +++ b/internal/online/wsclient/transport_test.go @@ -0,0 +1,90 @@ +package wsclient + +import ( + "context" + "crypto/ed25519" + "errors" + "log/slog" + "net/http" + "net/http/httptest" + "strings" + "sync/atomic" + "testing" + "time" + + "github.com/coder/websocket" + + "github.com/LensBridge/agent/internal/core/config" +) + +// A plaintext or foreign-host WebSocket URL is never dialled without the +// insecure_dev opt-in. +func TestRunRefusesInsecureWebSocketURL(t *testing.T) { + var hits atomic.Int32 + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { hits.Add(1) })) + defer srv.Close() + host := strings.TrimPrefix(srv.URL, "http://") + + for name, cfg := range map[string]*config.Config{ + "ws": {DeviceID: "d", BackendURL: srv.URL, WebSocketURL: "ws://" + host + "/ws"}, + "other host": {DeviceID: "d", BackendURL: "https://api.example.com", WebSocketURL: "wss://" + host + "/ws"}, + } { + t.Run(name, func(t *testing.T) { + c := New(cfg, nil, slog.New(slog.DiscardHandler), "test") + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + c.Run(ctx) // must return on its own + if ctx.Err() != nil { + t.Fatal("Run kept going") + } + if hits.Load() != 0 { + t.Errorf("dialled %d times", hits.Load()) + } + st := c.State() + if st.Connected || st.LastError == "" { + t.Errorf("state = %+v, want the reason in lastError", st) + } + if !errors.Is(cfg.CheckTransport(), config.ErrInsecureTransport) { + t.Errorf("CheckTransport = %v", cfg.CheckTransport()) + } + }) + } +} + +// A content_changed frame from the backend asks for a content sync. +func TestContentChangedFrame(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + c, err := websocket.Accept(w, r, nil) + if err != nil { + return + } + defer c.CloseNow() + ctx := r.Context() + c.Write(ctx, websocket.MessageText, []byte(`{"type":"hello","seq":1,"sessionId":"s","challenge":"c"}`)) + c.Read(ctx) // auth + c.Write(ctx, websocket.MessageText, []byte(`{"type":"auth_ok","seq":2,"sessionId":"s","deviceId":"d"}`)) + c.Write(ctx, websocket.MessageText, []byte(`{"type":"content_changed","seq":3,"sessionId":"s"}`)) + c.Write(ctx, websocket.MessageText, []byte(`{"type":"content_changed","seq":3,"sessionId":"s"}`)) + for { + if _, _, err := c.Read(ctx); err != nil { + return + } + } + })) + defer srv.Close() + on := true + host := strings.TrimPrefix(srv.URL, "http://") + cfg := &config.Config{DeviceID: "d", BackendURL: srv.URL, WebSocketURL: "ws://" + host + "/ws", InsecureDevSet: &on} + c := New(cfg, ed25519.NewKeyFromSeed(make([]byte, 32)), slog.New(slog.DiscardHandler), "test") + var changed atomic.Int32 + c.SetContentChanged(func() { changed.Add(1) }) + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + go c.Run(ctx) + for changed.Load() < 2 && ctx.Err() == nil { + time.Sleep(5 * time.Millisecond) + } + if changed.Load() != 2 { + t.Fatalf("content_changed handled %d times", changed.Load()) + } +} diff --git a/internal/wsclient/wsclient.go b/internal/online/wsclient/wsclient.go similarity index 93% rename from internal/wsclient/wsclient.go rename to internal/online/wsclient/wsclient.go index 190b643..9754a74 100644 --- a/internal/wsclient/wsclient.go +++ b/internal/online/wsclient/wsclient.go @@ -25,8 +25,7 @@ import ( "github.com/coder/websocket" - "github.com/LensBridge/agent/internal/config" - "github.com/LensBridge/agent/internal/telemetry" + "github.com/LensBridge/agent/internal/core/config" ) const ( @@ -68,11 +67,11 @@ type Client struct { priv ed25519.PrivateKey logger *slog.Logger agentVersion string - safeMode bool - onCommand CommandHandler - prober telemetry.PageProber - boardReport func() any + onCommand CommandHandler + onContentChanged func() + prober PageProber + boardReport func() any stateMu sync.Mutex state ConnState @@ -106,13 +105,12 @@ func (c *Client) setState(connected bool, err error) { } } -func New(cfg *config.Config, priv ed25519.PrivateKey, logger *slog.Logger, agentVersion string, safeMode bool) *Client { +func New(cfg *config.Config, priv ed25519.PrivateKey, logger *slog.Logger, agentVersion string) *Client { return &Client{ cfg: cfg, priv: priv, logger: logger, agentVersion: agentVersion, - safeMode: safeMode, } } @@ -120,10 +118,16 @@ func New(cfg *config.Config, priv ed25519.PrivateKey, logger *slog.Logger, agent // Must be called before Run; after Run starts, the field is read-only. func (c *Client) SetCommandHandler(h CommandHandler) { c.onCommand = h } +// SetContentChanged registers what a content_changed frame does (the +// backend sends one when the board's content may have changed): normally +// the content syncer's Trigger, which syncs soon and folds repeats. Must be +// called before Run. +func (c *Client) SetContentChanged(f func()) { c.onContentChanged = f } + // SetPageProber supplies the browser probe used to fill kioskAlive and // displayedFrameKey. Optional — without one, heartbeats fall back to the // systemd unit state. Must be called before Run. -func (c *Client) SetPageProber(p telemetry.PageProber) { c.prober = p } +func (c *Client) SetPageProber(p PageProber) { c.prober = p } // SetBoardReport supplies the board's own report for every heartbeat // (localserver.BoardReport). Optional. Must be called before Run. @@ -287,12 +291,11 @@ func (c *Client) serve(ctx context.Context, sess *session, hbInterval time.Durat func (c *Client) heartbeatLoop(ctx context.Context, sess *session, interval time.Duration) error { send := func() error { - snap := telemetry.Collect(ctx, c.agentVersion, c.safeMode, c.prober) hb := HeartbeatFrame{ Type: "heartbeat", Seq: sess.nextSeq(), SessionID: sess.sessionID, - Telemetry: TelemetryFromSnapshot(snap), + Telemetry: collectTelemetry(ctx, c.agentVersion, c.prober), } if c.boardReport != nil { hb.Telemetry.Board = c.boardReport() @@ -340,6 +343,11 @@ func (c *Client) readLoop(ctx context.Context, sess *session) error { } // Handlers run in a goroutine so a slow command doesn't block heartbeats. go c.onCommand(ctx, sessionSender{s: sess}, cmd) + case "content_changed": + c.logger.Info("backend says the content changed; syncing soon") + if c.onContentChanged != nil { + c.onContentChanged() + } default: c.logger.Debug("ignoring frame", "type", f.Type) } diff --git a/internal/safemode/safemode.go b/internal/safemode/safemode.go deleted file mode 100644 index 64bd6ea..0000000 --- a/internal/safemode/safemode.go +++ /dev/null @@ -1,73 +0,0 @@ -// Package safemode counts agent starts that did not lead to a stable run. -package safemode - -import ( - "fmt" - "os" - "path/filepath" - "strconv" - "strings" - - "github.com/LensBridge/agent/internal/fsutil" -) - -const ( - crashCounterFile = "crash-counter" - safeModeThreshold = 3 -) - -// Manager tracks consecutive failed agent runs via a file at -// $stateDir/crash-counter. Each startup increments it; OnSuccessfulRun -// resets it after the agent has been up long enough to be considered -// stable (typically 5 minutes — caller schedules that). -// -// If the counter exceeds safeModeThreshold, the agent is "in safe mode". -// That is a report, nothing more: the flag goes out with every backend -// heartbeat (telemetry safeMode) so the admin portal shows that the board is -// restarting over and over. The agent does not behave differently in safe -// mode, it does not refuse commands, and nothing stops the restarts: -// musallahboard-agent.service restarts the agent for ever -// (StartLimitIntervalSec=0), with a growing delay. A new agent that crashes -// in its first minutes after a self-update is rolled back by the root -// updater's probation (package selfupdate), independently of this counter. -type Manager struct { - path string -} - -func New(stateDir string) *Manager { - return &Manager{path: filepath.Join(stateDir, crashCounterFile)} -} - -// OnStartup increments the crash counter and returns true if the agent -// should boot in safe mode. -func (m *Manager) OnStartup() bool { - n := m.read() - n++ - m.write(n) - return n > safeModeThreshold -} - -// OnSuccessfulRun resets the crash counter — call this after the agent -// has been running long enough that we consider it stable. -func (m *Manager) OnSuccessfulRun() { - m.write(0) -} - -func (m *Manager) read() int { - b, err := os.ReadFile(m.path) - if err != nil { - return 0 - } - n, err := strconv.Atoi(strings.TrimSpace(string(b))) - if err != nil { - return 0 - } - return n -} - -func (m *Manager) write(n int) { - if err := os.MkdirAll(filepath.Dir(m.path), 0o755); err != nil { - return - } - _ = fsutil.WriteAtomic(m.path, []byte(fmt.Sprintf("%d\n", n)), 0o644) -} diff --git a/internal/safemode/safemode_test.go b/internal/safemode/safemode_test.go deleted file mode 100644 index dfa54fc..0000000 --- a/internal/safemode/safemode_test.go +++ /dev/null @@ -1,19 +0,0 @@ -package safemode - -import "testing" - -func TestSafeModeAfterRepeatedStarts(t *testing.T) { - m := New(t.TempDir()) - for i := 1; i <= safeModeThreshold; i++ { - if m.OnStartup() { - t.Fatalf("safe mode after %d starts", i) - } - } - if !m.OnStartup() { - t.Fatal("no safe mode after repeated starts") - } - m.OnSuccessfulRun() - if m.OnStartup() { - t.Fatal("safe mode after a stable run") - } -} diff --git a/internal/splash/splash.go b/internal/splash/splash.go deleted file mode 100644 index ce0f138..0000000 --- a/internal/splash/splash.go +++ /dev/null @@ -1,96 +0,0 @@ -// Package splash pushes live device information into the local "waiting for -// enrollment" page the kiosk shows before a device has a config. -// -// The splash is loaded from file:///usr/share/musallahboard/waiting.html. A -// file:// page has an opaque origin and cannot fetch anything — not the -// network, not another local file — so it has no way to discover the address -// of the machine it is running on. The agent has to push, and the channel it -// already owns is CDP Runtime.evaluate against the kiosk Chromium on :9222. -// This is the same trick config.refresh uses to repair an already-loaded -// board; here it feeds a page that has no network of its own. -// -// The page contract (see packaging/waiting.html): -// -// window.MusallahBoard.setNetInfo({ipv4, ssid, hostname, agentVersion}) → renders, no return -// -// Pushes are idempotent and stateless: the caller re-sends on a timer, so a -// kiosk restart (which wipes the injected values) self-heals on the next tick -// with no coordination between the two units. -package splash - -import ( - "context" - "encoding/json" - "errors" - "fmt" - "time" - - "github.com/LensBridge/agent/internal/cdp" - "github.com/LensBridge/agent/internal/netinfo" -) - -// Evaluator is the slice of *cdp.Client this package needs. -type Evaluator interface { - EvaluateValue(ctx context.Context, expression string, out any) error -} - -// ErrNoSplash means a page answered but is not the enrollment splash — the -// real board is loaded, or Chromium is still on about:blank. Callers polling -// on a timer should treat it as an ordinary skip, not a failure. -var ErrNoSplash = errors.New("splash: page does not expose window.MusallahBoard.setNetInfo") - -// pushTimeout bounds one CDP round trip. Chromium is on loopback, so this is -// generous; the point is that a wedged browser can never stall the -// pre-enrollment loop that calls us. -const pushTimeout = 5 * time.Second - -// netInfoScript builds the expression evaluated in the page. json.Marshal -// rather than string concatenation: hostname and SSID are attacker-adjacent -// (a hostile AP picks the SSID) and must not be able to break out of the -// literal and run as code in the kiosk browser. -func netInfoScript(info netinfo.Info, agentVersion string) (string, error) { - payload, err := json.Marshal(struct { - netinfo.Info - AgentVersion string `json:"agentVersion,omitempty"` - }{info, agentVersion}) - if err != nil { - return "", fmt.Errorf("splash: marshal net info: %w", err) - } - return `(() => { - const mb = window.MusallahBoard; - if (!mb || typeof mb.setNetInfo !== 'function') return false; - mb.setNetInfo(` + string(payload) + `); - return true; -})()`, nil -} - -// PushNetInfo renders info, and the running agent's version, onto the -// enrollment splash. -// -// Returns ErrNoSplash when the current page has no setNetInfo hook, and a -// wrapped transport error when Chromium is unreachable (not yet started, or -// mid-restart) — both are expected states while a board waits to be enrolled. -func PushNetInfo(ctx context.Context, ev Evaluator, info netinfo.Info, agentVersion string) error { - script, err := netInfoScript(info, agentVersion) - if err != nil { - return err - } - - cctx, cancel := context.WithTimeout(ctx, pushTimeout) - defer cancel() - - var applied bool - // ErrEvalUndefined would mean the expression itself did not resolve to a - // value, which our IIFE cannot do — but a page that failed to parse the - // script at all lands here, and "not the splash" is the right reading. - if err := ev.EvaluateValue(cctx, script, &applied); err != nil { - if errors.Is(err, cdp.ErrEvalUndefined) { - return ErrNoSplash - } - return err - } - if !applied { - return ErrNoSplash - } - return nil -} diff --git a/internal/splash/splash_test.go b/internal/splash/splash_test.go deleted file mode 100644 index 834ae11..0000000 --- a/internal/splash/splash_test.go +++ /dev/null @@ -1,129 +0,0 @@ -package splash - -import ( - "context" - "encoding/json" - "errors" - "fmt" - "strings" - "testing" - - "github.com/LensBridge/agent/internal/cdp" - "github.com/LensBridge/agent/internal/netinfo" -) - -// fakeEval records the expression it was handed and replays a canned outcome. -type fakeEval struct { - gotExpr string - applied bool - err error -} - -func (f *fakeEval) EvaluateValue(_ context.Context, expression string, out any) error { - f.gotExpr = expression - if f.err != nil { - return f.err - } - if p, ok := out.(*bool); ok { - *p = f.applied - } - return nil -} - -func TestPushNetInfoApplied(t *testing.T) { - ev := &fakeEval{applied: true} - info := netinfo.Info{IPv4: []string{"192.168.1.42"}, SSID: "MSA", Hostname: "lobby"} - - if err := PushNetInfo(context.Background(), ev, info, "0.3.0"); err != nil { - t.Fatalf("PushNetInfo() = %v, want nil", err) - } - if !strings.Contains(ev.gotExpr, "192.168.1.42") { - t.Errorf("expression does not carry the address:\n%s", ev.gotExpr) - } - if !strings.Contains(ev.gotExpr, `"agentVersion":"0.3.0"`) { - t.Errorf("expression does not carry the agent version:\n%s", ev.gotExpr) - } - if !strings.Contains(ev.gotExpr, "setNetInfo") { - t.Errorf("expression does not call the page hook:\n%s", ev.gotExpr) - } -} - -// A page that answers but has no hook is the board, or Chromium on about:blank. -// The poll loop must be able to tell that apart from a real failure. -func TestPushNetInfoNoHook(t *testing.T) { - ev := &fakeEval{applied: false} - if err := PushNetInfo(context.Background(), ev, netinfo.Info{}, ""); !errors.Is(err, ErrNoSplash) { - t.Fatalf("PushNetInfo() = %v, want ErrNoSplash", err) - } -} - -func TestPushNetInfoUndefinedIsNoSplash(t *testing.T) { - ev := &fakeEval{err: cdp.ErrEvalUndefined} - if err := PushNetInfo(context.Background(), ev, netinfo.Info{}, ""); !errors.Is(err, ErrNoSplash) { - t.Fatalf("PushNetInfo() = %v, want ErrNoSplash", err) - } -} - -// Chromium unreachable must surface as itself, not be swallowed as "no splash". -func TestPushNetInfoTransportErrorPropagates(t *testing.T) { - want := fmt.Errorf("chrome not reachable") - ev := &fakeEval{err: want} - err := PushNetInfo(context.Background(), ev, netinfo.Info{}, "") - if !errors.Is(err, want) { - t.Fatalf("PushNetInfo() = %v, want %v", err, want) - } - if errors.Is(err, ErrNoSplash) { - t.Error("transport failure was misreported as ErrNoSplash") - } -} - -// The SSID is chosen by whoever runs the access point. It lands in a string -// literal inside JS evaluated in the kiosk browser, so it has to be encoded, -// never concatenated. -func TestNetInfoScriptEscapesHostileFields(t *testing.T) { - info := netinfo.Info{ - IPv4: []string{"192.168.1.42"}, - SSID: `evil");alert("pwned`, - Hostname: "", - } - - script, err := netInfoScript(info, "") - if err != nil { - t.Fatalf("netInfoScript() error = %v", err) - } - - // The payload must be one JSON literal that round-trips to the original. - start := strings.Index(script, "mb.setNetInfo(") - if start < 0 { - t.Fatalf("no setNetInfo call in script:\n%s", script) - } - arg := script[start+len("mb.setNetInfo(") : strings.LastIndex(script, ");")] - - var got netinfo.Info - if err := json.Unmarshal([]byte(arg), &got); err != nil { - t.Fatalf("argument is not valid JSON (%v): %s", err, arg) - } - if !got.Equal(info) { - t.Errorf("round trip lost data: got %+v, want %+v", got, info) - } - // The quote that would have closed the JS string must be backslash-escaped, - // and the tag that would have closed the ") { - t.Errorf("payload contains a raw closing script tag: %s", arg) - } -} - -func TestNetInfoScriptOfflineDeviceStillPushes(t *testing.T) { - script, err := netInfoScript(netinfo.Info{Hostname: "lobby"}, "") - if err != nil { - t.Fatalf("netInfoScript() error = %v", err) - } - // An offline board must still reach the page: the splash renders "Not - // connected", which is what tells an operator the agent is alive at all. - if !strings.Contains(script, `"ipv4":null`) { - t.Errorf("expected an explicit empty address list:\n%s", script) - } -} diff --git a/internal/version/version.go b/internal/version/version.go index 131b76a..de55e7c 100644 --- a/internal/version/version.go +++ b/internal/version/version.go @@ -1,5 +1,6 @@ package version // Version is the agent build version. Override at build time: -// go build -ldflags "-X github.com/LensBridge/agent/internal/version.Version=0.1.0" +// +// go build -ldflags "-X github.com/LensBridge/agent/internal/version.Version=0.1.0" var Version = "dev" diff --git a/internal/wsclient/transport_test.go b/internal/wsclient/transport_test.go deleted file mode 100644 index d1cfc8b..0000000 --- a/internal/wsclient/transport_test.go +++ /dev/null @@ -1,49 +0,0 @@ -package wsclient - -import ( - "context" - "errors" - "log/slog" - "net/http" - "net/http/httptest" - "strings" - "sync/atomic" - "testing" - "time" - - "github.com/LensBridge/agent/internal/config" -) - -// A plaintext or foreign-host WebSocket URL is never dialled without the -// insecure_dev opt-in. -func TestRunRefusesInsecureWebSocketURL(t *testing.T) { - var hits atomic.Int32 - srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { hits.Add(1) })) - defer srv.Close() - host := strings.TrimPrefix(srv.URL, "http://") - - for name, cfg := range map[string]*config.Config{ - "ws": {DeviceID: "d", BackendURL: srv.URL, WebSocketURL: "ws://" + host + "/ws"}, - "other host": {DeviceID: "d", BackendURL: "https://api.example.com", WebSocketURL: "wss://" + host + "/ws"}, - } { - t.Run(name, func(t *testing.T) { - c := New(cfg, nil, slog.New(slog.DiscardHandler), "test", false) - ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) - defer cancel() - c.Run(ctx) // must return on its own - if ctx.Err() != nil { - t.Fatal("Run kept going") - } - if hits.Load() != 0 { - t.Errorf("dialled %d times", hits.Load()) - } - st := c.State() - if st.Connected || st.LastError == "" { - t.Errorf("state = %+v, want the reason in lastError", st) - } - if !errors.Is(cfg.CheckTransport(), config.ErrInsecureTransport) { - t.Errorf("CheckTransport = %v", cfg.CheckTransport()) - } - }) - } -} diff --git a/packaging/appliance-policy.sh b/packaging/appliance-policy.sh deleted file mode 100644 index 589913a..0000000 --- a/packaging/appliance-policy.sh +++ /dev/null @@ -1,64 +0,0 @@ -#!/bin/bash -# ===================================================== -# MusallahBoard appliance policy -# ===================================================== -# Turns a general-purpose Debian box into a board: no display manager, boots -# straight to multi-user.target where musallahboard-kiosk.service IS the -# graphical session. -# -# This is deliberately NOT part of packaging/install.sh, and will never be part -# of the .deb. Installing a package must not repoint the machine's default boot -# target or disable its display manager — that is the local administrator's -# decision, and a package that makes it for them is a package that breaks -# somebody's desktop. install.sh installs and enables the kiosk unit; this -# script is what makes the box actually boot into it. -# -# Callers: -# packaging/lib/common.sh (setup.sh — Raspberry Pi bare metal) -# image/scripts/* (Packer / image builds) -# -# Safe to re-run. Works with or without a live systemd: `set-default` and -# `disable` only rewrite symlinks, so they succeed in an image-build chroot. -# -# Usage: -# sudo bash appliance-policy.sh -# ===================================================== - -set -euo pipefail - -RED='\033[0;31m'; YELLOW='\033[1;33m'; GREEN='\033[0;32m'; BOLD='\033[1m'; NC='\033[0m' -info() { echo -e "${GREEN}[INFO]${NC} $*"; } -warn() { echo -e "${YELLOW}[WARN]${NC} $*"; } -error() { echo -e "${RED}[ERROR]${NC} $*"; exit 1; } -section() { echo; echo -e "${BOLD}═══ $* ═══${NC}"; } - -[[ $EUID -ne 0 ]] && error "Run as root: sudo bash $0" - -# `--now` needs a running manager; in a chroot we only rewrite the symlinks. -systemd_running() { [[ -d /run/systemd/system ]]; } - -section "Appliance boot policy" - -# The kiosk unit takes /dev/tty1 and owns the seat. A display manager competing -# for the same VT is the classic cause of a board that shows a login prompt, or -# a black screen, instead of the board. -if systemctl list-unit-files 2>/dev/null | grep -qE '^(lightdm|gdm3?|sddm)\.service'; then - if systemd_running; then - systemctl disable --now lightdm.service gdm.service gdm3.service sddm.service 2>/dev/null || true - else - systemctl disable lightdm.service gdm.service gdm3.service sddm.service 2>/dev/null || true - fi - info "Disabled display manager(s)" -else - info "No display manager installed — nothing to disable" -fi - -systemctl set-default multi-user.target >/dev/null -info "Default boot target: multi-user.target" - -target="$(systemctl get-default 2>/dev/null || echo unknown)" -[[ "$target" == "multi-user.target" ]] \ - || error "default target is '$target' after set-default — refusing to claim success" - -echo -info "Appliance policy applied. The kiosk unit is the graphical session." diff --git a/packaging/embed.go b/packaging/embed.go index 726292d..d91a62f 100644 --- a/packaging/embed.go +++ b/packaging/embed.go @@ -1,18 +1,67 @@ -// Package packaging embeds the files the agent installs itself, so a board -// set up by the curl|bash setup.sh (which has no repository checkout) gets the -// same bytes as one installed from this directory. +// Package packaging embeds the system files the agent installs itself: its +// systemd units, udev rules, sudoers allow-list, modules-load list, the kiosk +// launcher and the kiosk's local pages. `musallahboard-agent install-system` +// writes them (setup.sh runs it), so a board set up by the curl|bash setup.sh +// (which has no repository checkout) gets exactly these bytes, and there is +// one copy of each. package packaging -import _ "embed" +import ( + "embed" + "io/fs" +) -// WaitingHTML is waiting.html: the kiosk's "waiting for enrollment" splash, -// installed by `musallahboard-agent splash install`. -// -//go:embed waiting.html -var WaitingHTML []byte +//go:embed *.service *.path start-kiosk.sh starting.html udev sudoers.d modules-load.d rtc +var files embed.FS -// StartingHTML is starting.html: the kiosk's first page on an enrolled board, -// which waits for the agent to answer before moving to the board. -// -//go:embed starting.html -var StartingHTML []byte +// File is one system file: its name in this directory, where it goes, and +// its mode. +type File struct { + Name string + Path string + Mode fs.FileMode +} + +// Units are the systemd units every board has, enabled by install-system. +var Units = []string{ + "musallahboard-agent.service", + "musallahboard-kiosk.service", + "musallahboard-agent-update.path", +} + +// System is what every board gets. +var System = []File{ + {"musallahboard-agent.service", "/lib/systemd/system/musallahboard-agent.service", 0o644}, + {"musallahboard-kiosk.service", "/lib/systemd/system/musallahboard-kiosk.service", 0o644}, + {"musallahboard-agent-update.path", "/lib/systemd/system/musallahboard-agent-update.path", 0o644}, + {"musallahboard-agent-update.service", "/lib/systemd/system/musallahboard-agent-update.service", 0o644}, + {"musallahboard-usb-import@.service", "/lib/systemd/system/musallahboard-usb-import@.service", 0o644}, + {"udev/90-musallahboard-usb.rules", "/etc/udev/rules.d/90-musallahboard-usb.rules", 0o644}, + {"udev/90-musallahboard-rtc.rules", "/etc/udev/rules.d/90-musallahboard-rtc.rules", 0o644}, + {"sudoers.d/musallahboard-agent", "/etc/sudoers.d/musallahboard-agent", 0o440}, + {"modules-load.d/musallahboard.conf", "/etc/modules-load.d/musallahboard.conf", 0o644}, + {"start-kiosk.sh", "/usr/bin/start-kiosk.sh", 0o755}, + {"starting.html", "/usr/share/musallahboard/starting.html", 0o644}, +} + +// RTC is what a board with a DS3231 clock module also gets (--rtc). +var RTC = []File{ + {"rtc/85-musallahboard-rtc.rules", "/etc/udev/rules.d/85-musallahboard-rtc.rules", 0o644}, + {"rtc/musallahboard-rtc.service", "/lib/systemd/system/musallahboard-rtc.service", 0o644}, +} + +// Obsolete are files earlier versions installed and nothing uses any more; +// install-system removes them (units are disabled first). +var Obsolete = []string{ + // The kiosk loaded the URL in kiosk-url and was restarted when it + // changed; it always loads the local server now. + "/lib/systemd/system/musallahboard-kiosk-watch.path", + "/lib/systemd/system/musallahboard-kiosk-reload.service", + "/etc/musallahboard/kiosk-url", + // The enrollment splash; an unprovisioned board's screen is served by + // the local server now. + "/usr/share/musallahboard/waiting.html", +} + +// Read returns the embedded file named name. +func Read(name string) ([]byte, error) { return files.ReadFile(name) } diff --git a/packaging/install.sh b/packaging/install.sh deleted file mode 100644 index d62fe12..0000000 --- a/packaging/install.sh +++ /dev/null @@ -1,495 +0,0 @@ -#!/bin/bash -# ===================================================== -# MusallahBoard Agent Install Script -# ===================================================== -# Installs musallahboard-agent as a systemd service on -# a Debian/Ubuntu x86-64 or arm64 machine. -# -# SCOPE — this script installs PAYLOAD ONLY: files, accounts and unit -# enablement. It is written to be the .deb's postinst, so it deliberately does -# not do any of the following, all of which are host policy or per-device -# state and belong to the provisioner (packaging/lib/common.sh, the image -# build, or firstboot): -# -# - switching the default boot target / disabling display managers -# → packaging/appliance-policy.sh -# → provisioner or firstboot -# - the ethernet service port (NetworkManager profiles, ufw rules) -# → setup.sh --service-port -# - enrollment → firstboot, or by hand -# - hostname, SSH, UFW, watchdog, timezone, LUKS → common.sh / setup.sh -# -# It also assumes nothing about whether systemd is running: every operation -# that needs a live manager is skipped when there is no /run/systemd/system, -# so this works unchanged inside an image-build chroot. -# -# Usage: -# sudo bash install.sh [AGENT_DIR] [--token TOKEN] [--backend URL] -# -# AGENT_DIR Path to the agent source/build directory. -# Defaults to the directory containing this script. -# --token One-time enrollment token. If omitted, enrollment -# is skipped (run `musallahboard-agent enroll` later). -# --backend Backend base URL. Must be https (e.g. https://lensbridge.example). -# For a plain-http development backend, skip --token here and -# enroll on the board with `musallahboard-agent enroll --insecure-dev`. -# Required when --token is provided. -# --kiosk Install the cage kiosk unit + launcher. The display account is -# always `musallahkiosk` and is created here if absent — it is -# not configurable, because the unit that names it ships as a -# static file. Booting into it is a separate step; see -# packaging/appliance-policy.sh. -# ===================================================== - -set -euo pipefail - -# ── Colour helpers ──────────────────────────────────────────────────────────── -RED='\033[0;31m'; YELLOW='\033[1;33m'; GREEN='\033[0;32m'; BOLD='\033[1m'; NC='\033[0m' -info() { echo -e "${GREEN}[INFO]${NC} $*"; } -warn() { echo -e "${YELLOW}[WARN]${NC} $*"; } -error() { echo -e "${RED}[ERROR]${NC} $*"; exit 1; } -section() { echo; echo -e "${BOLD}═══ $* ═══${NC}"; } - -# ── systemd availability ────────────────────────────────────────────────────── -# True only when there is a live system manager to talk to. Inside an -# image-build chroot (mmdebstrap, debootstrap, packer provisioning a mounted -# root) there is not, and `systemctl start|restart|status|enable --now` all -# fail there. `systemctl enable` on its own is fine either way — it only -# writes symlinks — so it is not gated. -systemd_running() { [[ -d /run/systemd/system ]]; } - -# ── Constants ───────────────────────────────────────────────────────────────── -# Fixed, unconfigurable system account. It must match User=/Group= in -# musallahboard-agent.service and the first column of the sudoers allow-list; -# keeping all three hardcoded to the same name is what lets those files ship -# verbatim in a .deb rather than being templated at install time. -SERVICE_USER=musallahdaemon -# The display account. Also fixed: it is baked into User= and ExecStopPost in -# musallahboard-kiosk.service, which is what lets that unit ship as a static -# file. Deliberately NOT the same account as $SERVICE_USER — it runs Chromium -# against remote content, so a browser compromise must not reach the device's -# Ed25519 key or the sudo allow-list. -KIOSK_USER=musallahkiosk -BINARY_DEST=/usr/bin/musallahboard-agent -CONFIG_DIR=/etc/musallahboard -STATE_DIR=/var/lib/musallahboard -LOG_DIR=/var/log/musallahboard -CONFIG_PATH=${CONFIG_DIR}/agent.toml -SUDOERS_DEST=/etc/sudoers.d/musallahboard-agent -# /lib, not /etc: /etc/systemd/system belongs to the local administrator and is -# where the enable symlinks land. Package-shipped units go here, so an operator -# can still override any of them with a drop-in or a masking file in /etc. -UNIT_DIR=/lib/systemd/system -SERVICE_DEST=${UNIT_DIR}/musallahboard-agent.service -KIOSK_SERVICE_DEST=${UNIT_DIR}/musallahboard-kiosk.service -KIOSK_WATCH_DEST=${UNIT_DIR}/musallahboard-kiosk-watch.path -KIOSK_RELOAD_DEST=${UNIT_DIR}/musallahboard-kiosk-reload.service -KIOSK_LAUNCHER_DEST=/usr/bin/start-kiosk.sh -KIOSK_SHARE_DIR=/usr/share/musallahboard -# The root self-updater, the USB import helper and the udev rules that feed -# them (docs/architecture.md, sections 9.6 and 12). -UPDATE_PATH_DEST=${UNIT_DIR}/musallahboard-agent-update.path -UPDATE_SERVICE_DEST=${UNIT_DIR}/musallahboard-agent-update.service -USB_SERVICE_DEST=${UNIT_DIR}/musallahboard-usb-import@.service -UDEV_DIR=/etc/udev/rules.d -UDEV_RULES=(90-musallahboard-usb.rules 90-musallahboard-rtc.rules) -INBOX_DIR=${STATE_DIR}/inbox -LIB_DIR=/usr/lib/musallahboard -TRUST_PATH=${CONFIG_DIR}/trust.json - -# ── Arg parsing ─────────────────────────────────────────────────────────────── -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -AGENT_DIR="" -ENROLL_TOKEN="" -BACKEND_URL="" -WANT_KIOSK=no - -while [[ $# -gt 0 ]]; do - case "$1" in - --token) ENROLL_TOKEN="$2"; shift 2 ;; - --token=*) ENROLL_TOKEN="${1#--token=}"; shift ;; - --backend) BACKEND_URL="$2"; shift 2 ;; - --backend=*) BACKEND_URL="${1#--backend=}"; shift ;; - --kiosk) WANT_KIOSK=yes; shift ;; - --*) error "Unknown flag: $1" ;; - *) - [[ -n "$AGENT_DIR" ]] && error "Unexpected argument: $1" - AGENT_DIR="$1" - shift - ;; - esac -done - -AGENT_DIR="${AGENT_DIR:-$SCRIPT_DIR/..}" -AGENT_DIR="$(cd "$AGENT_DIR" && pwd)" - -# ── Pre-flight ──────────────────────────────────────────────────────────────── -[[ $EUID -ne 0 ]] && error "Run as root: sudo bash $0" - -[[ -n "$ENROLL_TOKEN" && -z "$BACKEND_URL" ]] && \ - error "--backend is required when --token is provided" - -section "Pre-flight" - -# Detect architecture and pick the right binary -ARCH="$(uname -m)" -case "$ARCH" in - x86_64) ARCH_SUFFIX=amd64 ;; - aarch64) ARCH_SUFFIX=arm64 ;; - *) error "Unsupported architecture: $ARCH" ;; -esac - -# Prefer the arch-specific binary; fall back to the plain one (native build). -# Also check the package root for release tarballs where the binary sits next -# to the packaging/ directory rather than under build/. -BINARY="" -for candidate in \ - "${AGENT_DIR}/build/musallahboard-agent-${ARCH_SUFFIX}" \ - "${AGENT_DIR}/build/musallahboard-agent" \ - "${AGENT_DIR}/musallahboard-agent-${ARCH_SUFFIX}" \ - "${AGENT_DIR}/musallahboard-agent" -do - if [[ -x "$candidate" ]]; then - BINARY="$candidate" - break - fi -done - -[[ -z "$BINARY" ]] && error "No binary found under ${AGENT_DIR}. Run 'make build' first." - -SUDOERS_SRC="${AGENT_DIR}/packaging/sudoers.d/musallahboard-agent" -SERVICE_SRC="${AGENT_DIR}/packaging/musallahboard-agent.service" -UPDATE_PATH_SRC="${AGENT_DIR}/packaging/musallahboard-agent-update.path" -UPDATE_SERVICE_SRC="${AGENT_DIR}/packaging/musallahboard-agent-update.service" -USB_SERVICE_SRC="${AGENT_DIR}/packaging/musallahboard-usb-import@.service" -UDEV_SRC_DIR="${AGENT_DIR}/packaging/udev" - -for f in "$SUDOERS_SRC" "$SERVICE_SRC" "$UPDATE_PATH_SRC" "$UPDATE_SERVICE_SRC" "$USB_SERVICE_SRC"; do - [[ -f "$f" ]] || error "Missing: $f" -done -for r in "${UDEV_RULES[@]}"; do - [[ -f "$UDEV_SRC_DIR/$r" ]] || error "Missing: $UDEV_SRC_DIR/$r" -done - -info "Agent directory : $AGENT_DIR" -info "Binary : $BINARY (arch: $ARCH_SUFFIX)" -info "Service user : $SERVICE_USER" -if [[ -n "$ENROLL_TOKEN" ]]; then - info "Enrollment : yes (backend: $BACKEND_URL)" -else - warn "Enrollment : skipped — run 'musallahboard-agent enroll' manually" -fi - -# ── Service user ────────────────────────────────────────────────────────────── -section "Service user: $SERVICE_USER" - -if id "$SERVICE_USER" &>/dev/null; then - info "User '$SERVICE_USER' already exists" -else - useradd --system --no-create-home --shell /usr/sbin/nologin "$SERVICE_USER" - info "Created system user '$SERVICE_USER'" -fi - -# systemd-journal membership lets the agent read the journal (for logs.tail). -if getent group systemd-journal &>/dev/null; then - usermod -aG systemd-journal "$SERVICE_USER" - info "Added '$SERVICE_USER' to systemd-journal group" -fi - -# video membership is what lets telemetry read /dev/vcio, which is root:video -# 0660 on Pi OS. Without it `vcgencmd get_throttled` fails and under-voltage / -# thermal-throttle reporting silently returns nothing on every board — the -# failure mode is missing data, not an error, so it is easy to miss. -if getent group video &>/dev/null; then - usermod -aG video "$SERVICE_USER" - info "Added '$SERVICE_USER' to video group (vcgencmd → /dev/vcio)" -fi - -# ── Directories ─────────────────────────────────────────────────────────────── -section "Directories" - -# Only the config dir is created here. $STATE_DIR and $LOG_DIR are declared as -# StateDirectory=/LogsDirectory= in musallahboard-agent.service, so systemd -# creates and chowns them on every start — one less thing for a postinst to get -# wrong, and it works even when this runs in a chroot. -# -# /etc/musallahboard cannot be handled that way: those directories only appear -# once the service has started, and `enroll` has to write agent.toml and -# agent.key before that has ever happened. -mkdir -p "$CONFIG_DIR" -# Owned by the service user so the agent can write its own config and key files -# at enrollment time and read them at runtime. The agent CLI's `enroll` -# subcommand chowns newly-written files to match this directory's owner, which -# means re-enrolling under `sudo` still leaves files owned by $SERVICE_USER -# rather than root. -chown "$SERVICE_USER:$SERVICE_USER" "$CONFIG_DIR" -# 0751 (not 0750): the unprivileged kiosk user must traverse this dir to read -# the agent-written kiosk-url file. 0751 grants traverse-by-path -# without directory listing; agent.key stays 0600 so it is unreadable anyway. -chmod 0751 "$CONFIG_DIR" - -info "Created $CONFIG_DIR ($SERVICE_USER 0751)" - -# The state dir is also StateDirectory= in the unit, but the inbox inside it is -# written by root tools (the USB helper, `musallahboard-agent import`) before -# the daemon may ever have started, so both are created here. The owner must -# match User= exactly: systemd recursively chowns a StateDirectory= whose top -# directory has the wrong owner, which would also hand the daemon the -# root-owned agent/last-update.json. -install -d -o "$SERVICE_USER" -g "$SERVICE_USER" -m 0750 "$STATE_DIR" -install -d -o "$SERVICE_USER" -g "$SERVICE_USER" -m 0770 "$INBOX_DIR" -info "Created $INBOX_DIR ($SERVICE_USER 0770)" -info "$LOG_DIR: created by systemd at first start" - -# Where the root self-updater keeps the previous agent binary for rollback. -install -d -o root -g root -m 0755 "$LIB_DIR" -info "Created $LIB_DIR (root 0755)" - -# ── Trust store ─────────────────────────────────────────────────────────────── -section "Trust store" - -# Root-owned and world-readable: the daemon reads it, only root changes it -# (`musallahboard-agent trust ...`, enrollment, the self-updater). Never -# overwritten: it holds the content keys pinned at enrollment, and release -# keys an admin may have added. An empty store is fine; release keys are also -# compiled into the agent, and content keys arrive with enrollment or -# `trust fetch`. -if [[ -e "$TRUST_PATH" ]]; then - info "Keeping existing $TRUST_PATH" -else - printf '{"content":[],"release":[]}\n' > "$TRUST_PATH.tmp" - chown root:root "$TRUST_PATH.tmp" - chmod 0644 "$TRUST_PATH.tmp" - mv -f "$TRUST_PATH.tmp" "$TRUST_PATH" - info "Created $TRUST_PATH (root 0644, no keys yet)" -fi - -# ── Binary ──────────────────────────────────────────────────────────────────── -section "Binary" - -install -o root -g root -m 0755 "$BINARY" "$BINARY_DEST" -info "Installed $BINARY_DEST" - -# ── Sudoers ─────────────────────────────────────────────────────────────────── -section "Sudoers" - -install -o root -g root -m 0440 "$SUDOERS_SRC" "$SUDOERS_DEST" -# Validate syntax — visudo -c exits non-zero if the file is broken -visudo -c -f "$SUDOERS_DEST" || { - rm -f "$SUDOERS_DEST" - error "Sudoers file failed validation — removed. Check $SUDOERS_SRC." -} -info "Installed $SUDOERS_DEST" - -# ── Systemd service ─────────────────────────────────────────────────────────── -section "Systemd service" - -install -o root -g root -m 0644 "$SERVICE_SRC" "$SERVICE_DEST" - -# Root self-updater (docs/architecture.md section 12): the .path unit watches -# for agent/staged/ready and starts the oneshot. Only the .path is enabled. -install -o root -g root -m 0644 "$UPDATE_PATH_SRC" "$UPDATE_PATH_DEST" -install -o root -g root -m 0644 "$UPDATE_SERVICE_SRC" "$UPDATE_SERVICE_DEST" -# USB import helper (section 9.6): a template started by udev, never enabled. -install -o root -g root -m 0644 "$USB_SERVICE_SRC" "$USB_SERVICE_DEST" - -systemd_running && systemctl daemon-reload -systemctl enable musallahboard-agent.service -systemctl enable musallahboard-agent-update.path -info "Service, self-updater and USB import units installed and enabled" - -# ── udev rules ──────────────────────────────────────────────────────────────── -section "udev rules" - -# USB sticks -> musallahboard-usb-import@.service, and rtc0 writable by -# the agent's group so it can save a corrected clock to the RTC. -mkdir -p "$UDEV_DIR" -for r in "${UDEV_RULES[@]}"; do - install -o root -g root -m 0644 "$UDEV_SRC_DIR/$r" "$UDEV_DIR/$r" -done -if systemd_running && command -v udevadm >/dev/null; then - udevadm control --reload || true - # Apply the rtc0 permissions now rather than at the next boot. Not a - # block-device trigger: that would import from a stick already plugged in. - udevadm trigger --subsystem-match=rtc --action=change || true -fi -info "Installed ${UDEV_RULES[*]} in $UDEV_DIR" - -# Filesystem drivers for USB sticks, loaded at boot: the USB helper's sandbox -# (ProtectKernelModules=yes) cannot load them itself. -install -d -m 0755 /etc/modules-load.d -install -o root -g root -m 0644 "${AGENT_DIR}/packaging/modules-load.d/musallahboard.conf" \ - /etc/modules-load.d/musallahboard.conf -if systemd_running; then - modprobe exfat 2>/dev/null || warn "Could not load exfat now; exFAT sticks work after a reboot" - modprobe ntfs3 2>/dev/null || warn "Could not load ntfs3 now; NTFS sticks work after a reboot" -fi -info "Installed /etc/modules-load.d/musallahboard.conf (exfat, ntfs3)" - -# ── Kiosk (cage + Chromium) ─────────────────────────────────────────────────── -if [[ "$WANT_KIOSK" == "yes" ]]; then - section "Kiosk (cage)" - - command -v cage >/dev/null || error "cage not installed (apt install cage)" - - # Display account. Needs a real home: start-kiosk.sh puts Chromium's - # profile in $HOME/.musallahboard-kiosk, which is mandatory rather than - # cosmetic — Chrome >=136 silently ignores --remote-debugging-port unless - # a non-default --user-data-dir is given, and the agent's CDP commands - # depend on that port. - # - # The shell stays /bin/bash rather than nologin: the unit runs with - # PAMName=login to get a logind seat, and some PAM stacks refuse a session - # for a nologin shell. The account is locked instead — no password, no SSH - # (sshd DenyUsers), and a .bashrc that exits on sight. - if id "$KIOSK_USER" &>/dev/null; then - info "User '$KIOSK_USER' already exists" - else - useradd -m -s /bin/bash "$KIOSK_USER" - info "Created user '$KIOSK_USER'" - fi - passwd -l "$KIOSK_USER" >/dev/null - # Strip every privilege group. video and render stay: cage needs DRM master - # and the browser needs the GPU. input stays off — cage gets its devices - # through the logind seat, not group membership. - for g in sudo adm dialout cdrom plugdev games users input netdev; do - gpasswd -d "$KIOSK_USER" "$g" 2>/dev/null || true - done - for g in video render; do - getent group "$g" >/dev/null && usermod -aG "$g" "$KIOSK_USER" - done - rm -f "/etc/sudoers.d/$KIOSK_USER" - cat > "/home/$KIOSK_USER/.bashrc" <<'BASHRC' -readonly PATH -echo "This account is for kiosk use only. Direct shell access is not permitted." -exit -BASHRC - printf 'export PATH="/home/%s/bin"\n' "$KIOSK_USER" > "/home/$KIOSK_USER/.bash_profile" - chown "$KIOSK_USER:$KIOSK_USER" \ - "/home/$KIOSK_USER/.bashrc" "/home/$KIOSK_USER/.bash_profile" - info "Kiosk user : $KIOSK_USER (locked, no sudo, no shell, video+render)" - - KIOSK_SERVICE_SRC="${AGENT_DIR}/packaging/musallahboard-kiosk.service" - KIOSK_WATCH_SRC="${AGENT_DIR}/packaging/musallahboard-kiosk-watch.path" - KIOSK_RELOAD_SRC="${AGENT_DIR}/packaging/musallahboard-kiosk-reload.service" - KIOSK_LAUNCHER_SRC="${AGENT_DIR}/packaging/start-kiosk.sh" - KIOSK_SPLASH_SRC="${AGENT_DIR}/packaging/waiting.html" - for f in "$KIOSK_SERVICE_SRC" "$KIOSK_WATCH_SRC" "$KIOSK_RELOAD_SRC" \ - "$KIOSK_LAUNCHER_SRC" "$KIOSK_SPLASH_SRC"; do - [[ -f "$f" ]] || error "Missing: $f" - done - - install -o root -g root -m 0755 "$KIOSK_LAUNCHER_SRC" "$KIOSK_LAUNCHER_DEST" - mkdir -p "$KIOSK_SHARE_DIR" - install -o root -g root -m 0644 "$KIOSK_SPLASH_SRC" "$KIOSK_SHARE_DIR/waiting.html" - install -o root -g root -m 0644 "${AGENT_DIR}/packaging/starting.html" "$KIOSK_SHARE_DIR/starting.html" - - # Copied verbatim — no substitution. The unit names $KIOSK_USER directly, - # which is the whole point of fixing the account name: a .deb ships static - # files and cannot template them at install time. - install -o root -g root -m 0644 "$KIOSK_SERVICE_SRC" "$KIOSK_SERVICE_DEST" - - # Watcher: reloads the kiosk the moment the agent (re)composes kiosk-url, - # so the splash is replaced by the board on enrollment with no operator - # action. No user substitution — these run as root in the system manager. - install -o root -g root -m 0644 "$KIOSK_WATCH_SRC" "$KIOSK_WATCH_DEST" - install -o root -g root -m 0644 "$KIOSK_RELOAD_SRC" "$KIOSK_RELOAD_DEST" - - # NOTE: switching the default boot target and disabling display managers - # used to happen here. It is host policy, not payload — a package that - # repoints your boot target is a package nobody wants — so it moved to - # packaging/appliance-policy.sh. Installing the kiosk unit does not by - # itself make the box boot into it. - systemd_running && systemctl daemon-reload - systemctl enable musallahboard-kiosk.service - # The .path watcher must be armed before the agent ever writes kiosk-url. - # The reload .service is pulled in by the path unit on demand — it is not - # enabled directly. `enable` alone is enough in a chroot (the unit starts - # at next boot); on a live system also start it now. - systemctl enable musallahboard-kiosk-watch.path - systemd_running && systemctl start musallahboard-kiosk-watch.path - info "Kiosk unit + URL watcher installed and enabled (user: $KIOSK_USER)" -fi - -# ── Enrollment ──────────────────────────────────────────────────────────────── -if [[ -n "$ENROLL_TOKEN" ]]; then - section "Enrollment" - - if [[ -f "$CONFIG_PATH" ]]; then - warn "Config already exists at $CONFIG_PATH — skipping enrollment." - warn "Delete it and re-run with --token to re-enroll." - else - # Run as root: enrollment also pins the backend's content signing keys - # in the root-owned trust.json. agent.toml and agent.key still end up - # owned by $SERVICE_USER, because enroll chowns the files it creates to - # the owner of the config directory. - "$BINARY_DEST" enroll \ - --token="$ENROLL_TOKEN" \ - --backend="$BACKEND_URL" \ - --config="$CONFIG_PATH" - info "Device enrolled. Config: $CONFIG_PATH" - fi - - # Whatever wrote it, trust.json is root's. - if [[ -f "$TRUST_PATH" ]]; then - chown root:root "$TRUST_PATH" - chmod 0644 "$TRUST_PATH" - fi -fi - -# ── Start the service ───────────────────────────────────────────────────────── -section "Service" - -# Everything below needs a live manager. In an image-build chroot the units are -# enabled and that is all that matters — they come up on the built board's -# first boot. -if ! systemd_running; then - info "No running systemd (chroot/image build) — units enabled, nothing started" -else - # Started with or without a config. An unenrolled agent no longer exits: it - # runs a pre-enrollment loop that paints this device's IP address onto the - # kiosk splash — which is how an operator finds the box to SSH into it — - # and picks up enrollment on its own, so nothing here has to be re-run. - systemctl restart musallahboard-agent.service - sleep 1 - systemctl status musallahboard-agent.service --no-pager --lines=5 - - systemctl start musallahboard-agent-update.path - - # Kiosk shows the splash immediately and the .path watcher swaps it for - # the board when the agent writes kiosk-url — safe to start either way. - if [[ "$WANT_KIOSK" == "yes" ]]; then - systemctl restart musallahboard-kiosk.service || true - info "Kiosk service (re)started" - fi - - if [[ ! -f "$CONFIG_PATH" ]]; then - warn "No config found — agent is waiting to be enrolled." - warn "The splash now shows this device's IP address." - warn "Run: musallahboard-agent enroll --token=X --backend=Y" - fi -fi - -# ── Summary ─────────────────────────────────────────────────────────────────── -cat << EOF - - ╔══════════════════════════════════════════════════════════╗ - ║ musallahboard-agent install complete ║ - ╚══════════════════════════════════════════════════════════╝ - - Binary : $BINARY_DEST - Config : $CONFIG_PATH - State : $STATE_DIR - Service : musallahboard-agent.service - Trust : $TRUST_PATH - Updates : USB stick, upload on the service port, or the release channel - (docs/architecture.md) - - Useful commands: - sudo systemctl status musallahboard-agent - sudo journalctl -u musallahboard-agent -f - sudo musallahboard-agent enroll --token=X --backend=Y - sudo musallahboard-agent status - sudo musallahboard-agent import - -EOF diff --git a/packaging/lib/common.sh b/packaging/lib/common.sh deleted file mode 100644 index 949dfba..0000000 --- a/packaging/lib/common.sh +++ /dev/null @@ -1,581 +0,0 @@ -# shellcheck shell=bash -# ===================================================== -# MusallahBoard setup — shared library -# ===================================================== -# Sourced by the thin per-platform wrapper: -# - setup.sh (Raspberry Pi, arm64) -# -# The wrapper sets a handful of variables and defines two hooks, then calls -# `musallahboard_setup_main`. Everything else — config prompts, users, SSH -# hardening, journal, firewall — lives here. -# -# x86-64 hosts are provisioned by the Packer image in ../../image, not by a -# wrapper here. The platform contract below stays generic so a second wrapper -# remains cheap to add. -# -# Contract the wrapper MUST satisfy before calling musallahboard_setup_main: -# -# PLATFORM_LABEL Human label, e.g. "Raspberry Pi (arm64)" -# PLATFORM_ARCH "arm64" | "amd64" — used only for the install.sh hint -# SSH_KEY_REQUIRED "yes" | "no" — Pi mandates a key; VM may skip -# REPO_ROOT Absolute path to the agent repo (has packaging/) -# -# platform_install_packages (function) installs the browser + platform -# packages and purges unwanted services. -# platform_after_hardening (function, optional) Pi-only extras: watchdog, -# WiFi power-save, Raspberry Pi Connect. Define -# an empty function if there is nothing to do. -# platform_finalize (function, optional) runs LAST, after the agent -# is installed. Anything that changes how the -# board boots belongs here, so that a failure -# earlier on leaves a machine that still boots. -# -# This file is sourced, never executed. It assumes `set -euo pipefail` was -# already set by the wrapper. -# ===================================================== - -# ── Colour helpers ──────────────────────────────────────────────────────────── -RED='\033[0;31m'; YELLOW='\033[1;33m'; GREEN='\033[0;32m'; BOLD='\033[1m'; NC='\033[0m' -info() { echo -e "${GREEN}[INFO]${NC} $*"; } -warn() { echo -e "${YELLOW}[WARN]${NC} $*"; } -error() { echo -e "${RED}[ERROR]${NC} $*"; exit 1; } -section() { echo; echo -e "${BOLD}═══ $* ═══${NC}"; } - -# ── Tunables ────────────────────────────────────────────────────────────────── -# How long to wait for the first NTP sync before giving up. Generous: a cold Pi -# on campus WiFi can take a while to associate before it can reach a time server. -NTP_SYNC_TIMEOUT_SEC="${NTP_SYNC_TIMEOUT_SEC:-90}" - -# ── Non-interactive configuration ───────────────────────────────────────────── -# Every prompt below can be answered in advance through an environment -# variable. That is what makes this usable from the one-line installer, where -# the script arrives down a pipe and stdin is the script itself rather than a -# person — a bare `read` there consumes the rest of the script instead of an -# answer, and does it silently. -# -# MB_HOSTNAME MB_ADMIN_USER MB_TIMEZONE -# MB_ADMIN_SSH_KEY -# MB_ASSUME_YES=1 take the default for anything unset, confirm nothing -# MB_REBOOT=auto|never|ask -# -# Anything left unset is still asked for interactively, so `bash setup.sh` by -# hand behaves exactly as it always has. -# -# The display account is fixed at `musallahkiosk`: musallahboard-kiosk.service -# names it in User= and ExecStopPost, and a .deb ships that unit as a static file. -MB_ASSUME_YES="${MB_ASSUME_YES:-0}" -MB_REBOOT="${MB_REBOOT:-ask}" - -# Fixed service accounts, both created by packaging/install.sh. Mirrored here -# only so prompts, the SSH deny-list and the summary can name them. -KIOSK_USER=musallahkiosk -SERVICE_USER=musallahdaemon - -# Read one answer: the pre-supplied value if there is one, otherwise a prompt, -# otherwise the default. Never prompts when there is no terminal on stdin — -# that case is not a user who wants defaults, it is a user who would never see -# the question. -# -# $1 variable to set $2 prompt text $3 default -_ask() { - local _var="$1" _prompt="$2" _default="$3" _preset _reply - _preset="${!_var-}" - - if [[ -n "$_preset" ]]; then - printf ' %-34s %s\n' "$_prompt" "$_preset" - return 0 - fi - - if [[ "$MB_ASSUME_YES" == "1" ]] || [[ ! -t 0 ]]; then - printf -v "$_var" '%s' "$_default" - printf ' %-34s %s (default)\n' "$_prompt" "$_default" - return 0 - fi - - read -rp "$(printf ' %-34s [%s]: ' "$_prompt" "$_default")" _reply - printf -v "$_var" '%s' "${_reply:-$_default}" - return 0 -} - -# Yes/no confirmation that defaults to yes under MB_ASSUME_YES and refuses to -# guess when there is no terminal. -_confirm() { - local _prompt="$1" _reply - [[ "$MB_ASSUME_YES" == "1" ]] && return 0 - [[ ! -t 0 ]] && return 0 - read -rp "$_prompt" -n 1 _reply; echo - [[ $_reply =~ ^[Yy]$ ]] -} - -# ── Pre-flight ──────────────────────────────────────────────────────────────── -_preflight() { - [[ $EUID -eq 0 ]] && error "Do not run as root. Run as a user with sudo access." - sudo -v || error "This script requires sudo access." - - : "${PLATFORM_LABEL:?wrapper must set PLATFORM_LABEL}" - : "${PLATFORM_ARCH:?wrapper must set PLATFORM_ARCH}" - : "${SSH_KEY_REQUIRED:?wrapper must set SSH_KEY_REQUIRED}" - : "${REPO_ROOT:?wrapper must set REPO_ROOT}" - declare -F platform_install_packages >/dev/null \ - || error "wrapper must define platform_install_packages()" - declare -F platform_after_hardening >/dev/null \ - || platform_after_hardening() { :; } - declare -F platform_finalize >/dev/null \ - || platform_finalize() { :; } -} - -_banner() { - cat << BANNER - - ╔══════════════════════════════════════════════╗ - ║ MusallahBoard Setup ║ - ║ ${PLATFORM_LABEL} - ║ Kiosk • Hardened SSH • Wayland/cage ║ - ╚══════════════════════════════════════════════╝ - -BANNER -} - -# ── Interactive configuration ───────────────────────────────────────────────── -_prompt_config() { - section "Configuration" - - # Seeded from the MB_* overrides so the same code path serves an interactive - # run and a piped one. HOSTNAME is assigned unconditionally on purpose: bash - # sets it to this machine's own name, which _ask would otherwise mistake for - # an answer somebody supplied and never ask the question. - HOSTNAME="${MB_HOSTNAME-}" - ADMIN_USER="${MB_ADMIN_USER-}" - TIMEZONE="${MB_TIMEZONE-}" - # The kiosk shows the board served by the local agent - # (docs/architecture.md section 14), so there is no URL to ask for. - KIOSK_URL="http://127.0.0.1:8080/" - - _ask HOSTNAME "Hostname for this board" "musallahboard" - _ask ADMIN_USER "Admin username (SSH/sudo)" "ibra" - _ask TIMEZONE "Timezone" "America/Toronto" - - # Three accounts, three trust levels, no overlap: - # $ADMIN_USER human login, passwordless sudo - # musallahkiosk runs Chromium against remote content; least trusted - # musallahdaemon holds the Ed25519 device key + the sudo allow-list - # - # Only the first is a choice. The other two are fixed because the systemd - # units and the sudoers allow-list name them literally — that is what lets - # those files ship verbatim in a .deb instead of being templated at install - # time. packaging/install.sh creates both; nothing here does. - # - # Aliasing any pair collapses a boundary: naming the human account - # `musallahdaemon` would hand the daemon NOPASSWD:ALL, and `musallahkiosk` - # would put the device key behind a browser exploit. - for _reserved in musallahdaemon "$KIOSK_USER"; do - [[ "$ADMIN_USER" == "$_reserved" ]] && \ - error "'$_reserved' is reserved for a MusallahBoard service account." - done - - echo - SSH_PUB_KEY="${MB_ADMIN_SSH_KEY-}" - if [[ -n "$SSH_PUB_KEY" ]]; then - info "SSH key supplied for $ADMIN_USER" - elif [[ -t 0 ]]; then - if [[ "$SSH_KEY_REQUIRED" == "yes" ]]; then - echo "Paste the SSH public key for $ADMIN_USER:" - read -rp "> " SSH_PUB_KEY - [[ -z "$SSH_PUB_KEY" ]] && error "SSH public key is required on this platform." - else - echo "Paste the SSH public key for $ADMIN_USER (blank to skip SSH hardening):" - read -rp "> " SSH_PUB_KEY - fi - elif [[ "$SSH_KEY_REQUIRED" == "yes" ]]; then - # No key, no terminal to ask on, and this platform mandates one. Failing - # here beats handing back a headless Pi whose only admin account cannot - # be logged into. - error "SSH public key is required on this platform. Pass MB_ADMIN_SSH_KEY." - fi - - echo - info "Summary" - printf " %-18s %s\n" "Platform:" "$PLATFORM_LABEL" - printf " %-18s %s\n" "Hostname:" "$HOSTNAME" - printf " %-18s %s\n" "Admin user:" "$ADMIN_USER (SSH key auth, passwordless sudo)" - printf " %-18s %s\n" "Kiosk user:" "$KIOSK_USER (auto-login, browser only, no sudo/SSH/shell)" - printf " %-18s %s\n" "Kiosk URL:" "$KIOSK_URL (served by the agent)" - printf " %-18s %s\n" "Timezone:" "$TIMEZONE" - [[ -z "$SSH_PUB_KEY" ]] && warn " No SSH key — password auth stays enabled; harden after testing." - echo - if ! _confirm "Continue? (y/n): "; then - exit 0 - fi - # Explicit: a trailing `cond && action` would make this function return the - # condition's (failed) status, which `set -e` turns into a silent - # whole-script abort in the caller. Always return success here. - return 0 -} - -# ── Hostname ────────────────────────────────────────────────────────────────── -_setup_hostname() { - section "Hostname" - - echo "$HOSTNAME" | sudo tee /etc/hostname > /dev/null - if grep -q "127\.0\.1\.1" /etc/hosts; then - sudo sed -i "s/^\(127\.0\.1\.1\s\+\).*/\1$HOSTNAME/" /etc/hosts - else - echo "127.0.1.1 $HOSTNAME" | sudo tee -a /etc/hosts > /dev/null - fi - sudo hostnamectl set-hostname "$HOSTNAME" - info "Hostname set to $HOSTNAME" -} - -# ── Clock ───────────────────────────────────────────────────────────────────── -# A Pi has no battery-backed RTC: after a power cut it boots with whatever time -# it last knew. Two things break on a wrong clock, and neither says so plainly: -# prayer times are computed against local midnight, and the backend refuses an -# agent handshake whose signature timestamp is more than five minutes out. So -# set the zone and refuse to finish setup until NTP has actually synced. -_setup_clock() { - section "Clock" - - if ! timedatectl list-timezones | grep -qx "$TIMEZONE"; then - error "Unknown timezone '$TIMEZONE' (see: timedatectl list-timezones)" - fi - sudo timedatectl set-timezone "$TIMEZONE" - info "Timezone set to $TIMEZONE" - - sudo systemctl enable --now systemd-timesyncd - sudo timedatectl set-ntp true - - info "Waiting for NTP sync (up to ${NTP_SYNC_TIMEOUT_SEC}s)…" - local waited=0 - while [[ $waited -lt $NTP_SYNC_TIMEOUT_SEC ]]; do - if [[ "$(timedatectl show --property=NTPSynchronized --value)" == "yes" ]]; then - info "Clock synced: $(date)" - return 0 - fi - sleep 2 - waited=$((waited + 2)) - done - - error "Clock did not sync within ${NTP_SYNC_TIMEOUT_SEC}s. - Prayer times and agent authentication both depend on it, so setup stops here. - Check outbound NTP (udp/123) and rerun, or fix the clock by hand: - sudo timedatectl set-ntp true - timedatectl status" -} - -# ── Admin user ──────────────────────────────────────────────────────────────── -_setup_admin_user() { - section "Admin user: $ADMIN_USER" - - if ! id "$ADMIN_USER" &>/dev/null; then - sudo useradd -m -s /bin/bash "$ADMIN_USER" - info "Created user $ADMIN_USER" - else - info "User $ADMIN_USER already exists" - fi - - sudo usermod -aG sudo "$ADMIN_USER" - echo "$ADMIN_USER ALL=(ALL) NOPASSWD:ALL" | sudo tee "/etc/sudoers.d/$ADMIN_USER" > /dev/null - sudo chmod 440 "/etc/sudoers.d/$ADMIN_USER" - - if [[ -n "$SSH_PUB_KEY" ]]; then - sudo mkdir -p "/home/$ADMIN_USER/.ssh" - sudo chmod 700 "/home/$ADMIN_USER/.ssh" - echo "$SSH_PUB_KEY" | sudo tee "/home/$ADMIN_USER/.ssh/authorized_keys" > /dev/null - sudo chmod 600 "/home/$ADMIN_USER/.ssh/authorized_keys" - sudo chown -R "$ADMIN_USER:$ADMIN_USER" "/home/$ADMIN_USER/.ssh" - info "$ADMIN_USER configured with SSH key auth and passwordless sudo" - else - warn "No SSH key provided — skipping authorized_keys for $ADMIN_USER" - fi -} - -# ── Kiosk user ──────────────────────────────────────────────────────────────── -# Deliberately absent. Both $KIOSK_USER and $SERVICE_USER are created and -# locked down by packaging/install.sh, which is the code that will become the -# .deb's postinst — keeping account creation in one place stops the host -# provisioner and the package from drifting into two different lockdowns. -# _harden_ssh still names $KIOSK_USER in DenyUsers; that is just a config -# string and does not require the account to exist yet. - -# ── Kiosk display stack ─────────────────────────────────────────────────────── -_setup_display_stack() { - section "Kiosk display stack" - - # cage (the single-app Wayland kiosk compositor), the kiosk systemd unit, - # the launcher and the splash are all installed by packaging/install.sh — - # the separate agent step. That step disables any display manager and sets - # the boot target to multi-user; the cage unit *is* the graphical session. - # Until install.sh runs there is no kiosk. - command -v cage >/dev/null \ - && info "cage present" \ - || warn "cage not yet installed — packaging/install.sh installs it" - - sudo mkdir -p /etc/musallahboard - - # Software-rendering fallback: a virtual GPU can't scan out GBM/DMA-BUF - # buffers, so wlroots must fall back to pixman or cage shows a blank - # screen. Detect virtualization rather than hardcode per platform — this - # covers a Pi in a VM and bare-metal x86 alike. The kiosk unit reads this - # via EnvironmentFile=-/etc/musallahboard/kiosk.env; on real hardware the - # file is absent and GL acceleration is kept. - if systemd-detect-virt --quiet 2>/dev/null; then - sudo tee /etc/musallahboard/kiosk.env > /dev/null << 'EOF' -WLR_RENDERER=pixman -WLR_NO_HARDWARE_CURSORS=1 -WLR_DRM_NO_MODIFIERS=1 -EOF - sudo chmod 0644 /etc/musallahboard/kiosk.env - info "Virtualized host detected — wrote kiosk.env (software-render fallback)" - else - sudo rm -f /etc/musallahboard/kiosk.env - info "Bare-metal host — keeping hardware GL (no kiosk.env)" - fi -} - -# ── Disable tty1 autologin ──────────────────────────────────────────────────── -_disable_tty1_autologin() { - section "Disable tty1 autologin" - - # Prevents physical-access privilege escalation via VT switch to a root - # shell. The kiosk unit takes tty1 (Conflicts=getty@tty1.service). - sudo rm -f /etc/systemd/system/getty@tty1.service.d/autologin.conf - sudo systemctl daemon-reload - info "tty1 autologin removed" -} - -# ── SSH hardening ───────────────────────────────────────────────────────────── -_harden_ssh() { - section "SSH hardening" - - sudo mkdir -p /etc/ssh/sshd_config.d - sudo tee /etc/ssh/sshd_config.d/kiosk-hardening.conf > /dev/null << EOF -# Password auth disabled only once a key is installed for the admin user. -PasswordAuthentication $([ -n "$SSH_PUB_KEY" ] && echo no || echo yes) -ChallengeResponseAuthentication no -PubkeyAuthentication yes - -# No root login -PermitRootLogin no - -# Only the admin user may SSH in; deny kiosk user explicitly -AllowUsers $ADMIN_USER -DenyUsers $KIOSK_USER -EOF - - sudo systemctl reload ssh 2>/dev/null || sudo systemctl reload sshd 2>/dev/null || true - - if [[ -n "$SSH_PUB_KEY" ]]; then - info "SSH: key-based auth only, $ADMIN_USER access only" - warn "Verify you can SSH as $ADMIN_USER before closing this session!" - else - warn "SSH: password auth left enabled (no key provided) — harden after testing" - fi -} - -# ── logind: ignore idle/power on a display-only device ──────────────────────── -_setup_logind() { - section "logind (idle/power key)" - - sudo mkdir -p /etc/systemd/logind.conf.d - sudo tee /etc/systemd/logind.conf.d/kiosk.conf > /dev/null << 'EOF' -[Login] -IdleAction=ignore -HandlePowerKey=ignore -HandleLidSwitch=ignore -EOF - info "logind: idle/power/lid actions ignored" -} - -# ── Persistent, size-capped journal ─────────────────────────────────────────── -_setup_journal() { - section "Journal (persistent, size-capped)" - - # Persistent storage means logs survive reboots — critical for post-mortem - # diagnosis. Without this journald keeps logs in RAM only. - sudo mkdir -p /var/log/journal - sudo systemd-tmpfiles --create --prefix /var/log/journal - - sudo mkdir -p /etc/systemd/journald.conf.d - sudo tee /etc/systemd/journald.conf.d/size.conf > /dev/null << 'EOF' -[Journal] -Storage=persistent -SystemMaxUse=100M -RuntimeMaxUse=20M -Compress=yes -EOF - - sudo systemctl restart systemd-journald - info "Journal: persistent, 100 MB cap — 'sudo journalctl -b -1' shows previous boot" -} - -# ── Unattended security upgrades ────────────────────────────────────────────── -_setup_unattended_upgrades() { - section "Unattended security upgrades" - - sudo tee /etc/apt/apt.conf.d/20auto-upgrades > /dev/null << 'EOF' -APT::Periodic::Update-Package-Lists "1"; -APT::Periodic::Unattended-Upgrade "1"; -APT::Periodic::AutocleanInterval "7"; -EOF - info "Unattended security upgrades enabled" -} - -# ── UFW firewall ────────────────────────────────────────────────────────────── -_setup_ufw() { - section "UFW firewall" - - sudo ufw default deny incoming - sudo ufw default allow outgoing - sudo ufw allow ssh - sudo ufw --force enable - info "Firewall: deny inbound except SSH" -} - -# ── Install agent + kiosk (everything except enrollment) ────────────────────── -# Runs packaging/install.sh WITHOUT --token/--backend: the binary, the cage -# kiosk unit and the systemd service all get installed and enabled, the box is -# switched to boot into the kiosk, and the splash shows — the device is left -# fully provisioned and *ready for enrollment*. The only remaining manual step -# is `musallahboard-agent enroll`, which the operator runs once with a -# one-time token from the admin UI. -_install_agent() { - section "Agent + kiosk install" - - # Locate the built binary. Match on existence, NOT the +x bit — binaries - # copied from Windows/scp routinely lose execute permission; install.sh - # re-installs them 0755 anyway. Prefer the arch-specific build. - local cand AGENT_BINARY="" - for cand in \ - "$REPO_ROOT/build/musallahboard-agent-$PLATFORM_ARCH" \ - "$REPO_ROOT/build/musallahboard-agent" \ - "$REPO_ROOT/musallahboard-agent-$PLATFORM_ARCH" \ - "$REPO_ROOT/musallahboard-agent" - do - if [[ -f "$cand" ]]; then - AGENT_BINARY="$cand" - chmod +x "$cand" 2>/dev/null || true - break - fi - done - - if [[ -z "$AGENT_BINARY" ]]; then - AGENT_INSTALLED="no" - warn "No agent binary found under $REPO_ROOT (looked in build/ and repo root)." - warn "Build it, then run install.sh yourself:" - warn " make build-$PLATFORM_ARCH" - warn " sudo bash $REPO_ROOT/packaging/install.sh \"$REPO_ROOT\" --kiosk" - warn " sudo bash $REPO_ROOT/packaging/appliance-policy.sh" - return 0 - fi - - info "Agent binary : $AGENT_BINARY" - # install.sh is payload only: files, accounts, unit enablement. It does not - # touch the boot target — that is appliance-policy.sh, below. - sudo bash "$REPO_ROOT/packaging/install.sh" "$REPO_ROOT" --kiosk - sudo bash "$REPO_ROOT/packaging/appliance-policy.sh" - AGENT_INSTALLED="yes" - info "Agent + kiosk installed and enabled (enrollment still pending)" -} - -# ── Summary + reboot ────────────────────────────────────────────────────────── -_print_summary() { - cat << EOF - - ╔══════════════════════════════════════════════════════════╗ - ║ Setup complete — device READY FOR ENROLLMENT ║ - ╚══════════════════════════════════════════════════════════╝ - - Hostname : $HOSTNAME - Admin SSH : ssh $ADMIN_USER@ - Kiosk URL : $KIOSK_URL (served by the agent) - -EOF - - if [[ "${AGENT_INSTALLED:-no}" == "yes" ]]; then - cat << EOF - FINAL STEP — enroll this device (once, with a token from the admin UI): - - sudo musallahboard-agent enroll \\ - --token= --backend= - - Until then the kiosk shows the local "waiting" splash. On enrollment the - kiosk switches to the board served by the agent, which starts syncing - content right away, with no reboot needed. - - ✓ Boots multi-user → musallahboard-kiosk.service → cage → browser - ✓ SSH as $ADMIN_USER to manage the system - ✗ $KIOSK_USER has no SSH, no sudo, no shell - ✗ No display manager; tty1 is owned by the kiosk unit - -EOF - else - cat << EOF - Host is prepared but the agent/kiosk are NOT installed (no binary found). - Build + install, then enroll — see the warnings above. - -EOF - fi - - [[ -n "$SSH_PUB_KEY" ]] && warn "Verify SSH works as $ADMIN_USER before rebooting!" - - # When the encryption has been armed the reboot is not a formality — it is - # the step that does the conversion — so say so rather than offering the - # same bare y/n as always. - if [[ "${LUKS_ARMED:-no}" == "yes" ]]; then - echo - warn "The next boot converts the root filesystem. It will sit on the" - warn "console saying DO NOT POWER OFF for several minutes." - fi - - echo - case "$MB_REBOOT" in - never) - info "Not rebooting (MB_REBOOT=never). Reboot when you are ready." - ;; - auto) - info "Rebooting now (MB_REBOOT=auto)." - sudo reboot - ;; - *) - if _confirm "Reboot now? (y/n): "; then - sudo reboot - fi - ;; - esac - return 0 -} - -# ── Orchestration ───────────────────────────────────────────────────────────── -musallahboard_setup_main() { - _preflight - _banner - _prompt_config - - section "Installing packages" - sudo apt-get update -qq - platform_install_packages # wrapper-provided: browser + platform pkgs - - _setup_hostname - _setup_clock - _setup_admin_user - # No _setup_kiosk_user — packaging/install.sh creates and locks down both - # service accounts. See the "Kiosk user" note further up this file. - _setup_display_stack - _disable_tty1_autologin - _harden_ssh - _setup_logind - _setup_journal - _setup_unattended_upgrades - _setup_ufw - - platform_after_hardening # wrapper-provided: Pi-only extras (or noop) - - _install_agent # runs install.sh (no enrollment) - - # Last, and deliberately so. platform_finalize is where the boot files get - # pointed at an encrypted root; doing it before the agent install would mean - # a board that had committed to the conversion and then failed to provision. - platform_finalize - - _print_summary -} diff --git a/packaging/luks/initramfs-hook b/packaging/luks/initramfs-hook deleted file mode 100644 index 5257292..0000000 --- a/packaging/luks/initramfs-hook +++ /dev/null @@ -1,172 +0,0 @@ -#!/bin/sh -# ===================================================== -# initramfs hook — pull the LUKS/OTP toolchain into the initramfs -# ===================================================== -# Installed as /etc/initramfs-tools/hooks/musallahboard-luks by -# packaging/luks/install.sh (bare metal) or by image/scripts/60-luks.sh -# (rpi-image-gen builds). Both paths ship the same files. -# -# Everything the local-top script touches has to be listed here. An initramfs is -# not the rootfs: if a binary is not copied in, the failure surfaces at boot on a -# wall-mounted board as "command not found" scrolling past on a screen nobody is -# watching. Missing tools are therefore a HARD FAILURE of update-initramfs, which -# in turn fails the installer — the only place this is cheap to fix. -# -# Deliberately not relying on busybox applets for anything load-bearing. Most of -# these do exist in Debian's busybox, but "most" is not a property worth betting -# a fleet's boot path on, and the applet set is a packaging detail that can -# change under us. -# ===================================================== -set -e - -PREREQ="" -prereqs() { echo "$PREREQ"; } -case "${1:-}" in - prereqs) prereqs; exit 0 ;; -esac - -. /usr/share/initramfs-tools/hook-functions - -need() { - _p="$(command -v "$1" 2>/dev/null || true)" - if [ -z "$_p" ]; then - echo "musallahboard-luks hook: FATAL: $1 not found on the system" >&2 - echo " The initramfs would boot without it and silently skip encryption." >&2 - exit 1 - fi - copy_exec "$_p" -} - -# Optional: the local-top script guards every use of these and degrades to a -# board that is encrypted but has not taken the whole card. Worth copying, not -# worth failing a build over. -want() { - _p="$(command -v "$1" 2>/dev/null || true)" - [ -n "$_p" ] && copy_exec "$_p" || true -} - -# ── Disk encryption ────────────────────────────────────────────────────────── -need cryptsetup - -# ── OTP access ─────────────────────────────────────────────────────────────── -# vcmailbox comes from raspi-utils-core; rpi-otp-private-key from rpi-eeprom. -# The latter is a /bin/sh script, which is why the utilities it shells out to -# below are not optional. -need vcmailbox -need rpi-otp-private-key -need musallahboard-otp-key - -# ── Everything the two shell scripts shell out to ──────────────────────────── -# rpi-otp-private-key uses sed/awk/tr/cut/wc/od/grep/which for its mailbox -# response parsing and board detection; musallahboard-otp-key adds sha256sum; -# the local-top script adds readlink for resolving symlinks. -for t in sed awk tr cut wc od grep which sha256sum readlink; do - need "$t" -done - -# blkid resolves mb_rootdev=PARTUUID=/UUID=/LABEL= when the corresponding -# /dev/disk/by-* symlink has not appeared. On a bare-metal install that tag IS -# the only description of the root device the initramfs has, so the fallback is -# not decorative. -need blkid - -# ── Filesystem surgery for the one-time conversion ─────────────────────────── -for t in e2fsck resize2fs tune2fs blockdev; do - need "$t" -done - -# ── Resizing the root partition around the conversion ──────────────────────── -# Both directions need a partition editor. A bare-metal Raspberry Pi OS install -# has already grown its root to fill the card, so the local-top script shrinks -# it down to the filesystem before encrypting and grows it back afterwards — -# otherwise the one-time reencryption is proportional to card size rather than -# to the data on it. An rpi-image-gen image starts small and only grows. -need sfdisk -want partx -want udevadm - -# ── Cipher choice ──────────────────────────────────────────────────────────── -# Written by whichever installer ran: packaging/luks/install.sh detects the SoC -# on the board itself, image/scripts/60-luks.sh knows the device class at build -# time. Either way it is carried into the initramfs because the conversion -# happens there. -# -# Read here too, so that only the modules the chosen cipher actually needs get -# copied in. -MB_LUKS_CONF=/etc/musallahboard/luks.conf -if [ -r "$MB_LUKS_CONF" ]; then - . "$MB_LUKS_CONF" - copy_file config "$MB_LUKS_CONF" /etc/musallahboard/luks.conf -else - echo "musallahboard-luks hook: FATAL: ${MB_LUKS_CONF} not found" >&2 - echo " The installer writes it before building the initramfs. Without it the" >&2 - echo " board would pick a cipher at conversion time with no idea what SoC" >&2 - echo " it is running on." >&2 - exit 1 -fi - -# ── Rehearsal key ──────────────────────────────────────────────────────────── -# Present only when the installer was run with --dry-run-otp. It stands in for -# the SoC's OTP so that the whole conversion — real initramfs, real -# reencryption, real reboot — can be exercised on a real board without spending -# its one permanent write. -# -# Pre-populated at install time rather than generated on the board, because -# --ensure would otherwise try to write it into a read-only initramfs. -# -# A board carrying this file is NOT protected: its disk key sits in an -# unencrypted initramfs on a FAT partition. That is the point of a rehearsal, -# and it is why the installer prints what it prints. -MB_OTP_DRY_RUN_FILE=/etc/musallahboard/otp-dry-run.key -if [ -r "$MB_OTP_DRY_RUN_FILE" ]; then - copy_file config "$MB_OTP_DRY_RUN_FILE" /etc/musallahboard/otp-dry-run.key - echo "musallahboard-luks hook: REHEARSAL key included — this board's" >&2 - echo " encryption will NOT be keyed to its SoC." >&2 -fi - -# ── Kernel modules ─────────────────────────────────────────────────────────── -# Listed explicitly because an initramfs.conf set to MODULES=dep would otherwise -# produce an image that builds cleanly, passes verification, and cannot open its -# own root filesystem. -manual_add_modules dm_mod -manual_add_modules dm_crypt - -# Hashes cryptsetup needs for the LUKS2 header itself, whatever the data cipher. -for m in sha256 sha512 crypto_null; do - manual_add_modules "$m" || true -done - -# The data cipher. Soft-added — module names move between kernel versions and -# arm64 ships accelerated variants under different names — and then hard -# asserted by the installer against the finished initramfs. Guessing wrong here -# fails the install; it does not reach a running board. -case "${MB_LUKS_CIPHER:-}" in - aes-xts-plain64) - for m in aes xts aes_generic aes-neon-bs aes-neon-blk; do - manual_add_modules "$m" || true - done - ;; - xchacha12,aes-adiantum-plain64) - # Adiantum is XChaCha12 over NH/Poly1305 with AES underneath, so all - # four families have to be present. On arm64 the accelerated chacha and - # nhpoly1305 live under -neon names. - for m in adiantum nhpoly1305 nhpoly1305-neon \ - chacha chacha_generic chacha-neon libchacha \ - poly1305 poly1305_generic \ - aes aes_generic; do - manual_add_modules "$m" || true - done - ;; - *) - echo "musallahboard-luks hook: FATAL: unknown cipher '${MB_LUKS_CIPHER:-}'" >&2 - exit 1 - ;; -esac - -# No vfat or nls modules. Neither delivery path rewrites cmdline.txt from inside -# the initramfs: the rpi-image-gen path does not need to because -# /dev/disk/by-slot/system resolves to the open mapper, and the bare-metal path -# has already done it from a running system where the result could be checked. -# See packaging/luks/initramfs-local-top. - -exit 0 diff --git a/packaging/luks/initramfs-local-top b/packaging/luks/initramfs-local-top deleted file mode 100644 index 2f2d1ab..0000000 --- a/packaging/luks/initramfs-local-top +++ /dev/null @@ -1,589 +0,0 @@ -#!/bin/sh -# ===================================================== -# musallahboard-luks — unlock, or one-time encrypt, the root filesystem -# ===================================================== -# Installed as /etc/initramfs-tools/scripts/local-top/musallahboard-luks. -# -# local-top runs unconditionally, and — confirmed against initramfs-tools -# 0.148.4's local_mount_root() — it runs BEFORE local_device_setup resolves -# ROOT. That ordering is the whole design: this script can create -# /dev/mapper/musallahroot and by the time init looks for the root device it is -# simply there. No crypttab, no cryptsetup-initramfs, no rewriting ROOT. -# -# Debian's initramfs-tools has no /conf/param.conf (that is an Ubuntu -# extension), so a script CANNOT hand a modified ROOT back to init. Anything -# that depends on doing so will appear to work and then fail on the device. -# -# ── HOW THE DEVICE IS FOUND ────────────────────────────────────────────────── -# -# Two delivery paths put this script on two different kinds of system, and they -# describe the root device differently. The mode is chosen by whether -# mb_rootdev= is on the kernel command line — an explicit tag, not a probe, so -# there is never a boot where the answer depends on timing. -# -# BY-SLOT MODE (rpi-image-gen images; no mb_rootdev=) -# image-rpios ships 99-rpi-05-image.rules, which is copied into the -# initramfs, and which keys purely on filesystem label plus "is this -# partition on the device we booted from": -# -# ID_FS_LABEL=ROOT -> /dev/disk/by-slot/system -# ID_FS_LABEL=OSROOT_CRYPT -> /dev/disk/by-slot/cryptroot -# -# So the conversion gives the LUKS2 container the label OSROOT_CRYPT and -# gets by-slot/cryptroot for free. The inner ext4 keeps its ROOT label, and -# because rpi-storage-binder's rules walk the device-mapper slaves chain, -# the OPEN MAPPER is what by-slot/system resolves to from then on. -# -# The consequence is worth stating plainly: root=/dev/disk/by-slot/system in -# cmdline.txt and in fstab are correct both before and after encryption, and -# neither file is ever rewritten on the device. -# -# ROOTDEV MODE (bare-metal Raspberry Pi OS; mb_rootdev=PARTUUID=...) -# Stock Raspberry Pi OS has none of those udev rules. Instead the installer -# — which runs on a booted system, where the result can be checked before -# rebooting — has already pointed root= and fstab at /dev/mapper/musallahroot -# and recorded the underlying partition as mb_rootdev=. Here ONE partition -# is both the before and the after, so `cryptsetup isLuks` is what decides -# between converting and unlocking. -# -# mb_rootdev MUST name the partition, not the filesystem: a PARTUUID lives -# in the partition table and survives the conversion untouched, whereas a -# filesystem UUID or LABEL moves inside the container and stops resolving -# the moment the board is encrypted. UUID= and LABEL= are refused below -# rather than accepted into a boot that would work exactly once. -# -# ── STATES ─────────────────────────────────────────────────────────────────── -# -# 1. the device is a LUKS container -> derive the key from OTP and open it. -# Every boot after the conversion. -# 2. it is not -> convert. ONCE PER BOARD, and the OTP -# burn inside it is PERMANENT. -# -# POSIX sh. There is no bash here. -# ===================================================== - -PREREQ="" -prereqs() { echo "$PREREQ"; } -case "${1:-}" in - prereqs) prereqs; exit 0 ;; -esac - -. /scripts/functions - -MAPPER_NAME="musallahroot" -MAPPER="/dev/mapper/${MAPPER_NAME}" - -BY_SLOT_SYSTEM="/dev/disk/by-slot/system" -BY_SLOT_CRYPT="/dev/disk/by-slot/cryptroot" - -# The label the by-slot udev rule matches on. Changing this string orphans every -# board already in the field. In rootdev mode it is not load-bearing — discovery -# is by PARTUUID — but it is still set, so that a card pulled from a board and -# inspected on a laptop identifies itself. -CRYPT_LABEL="OSROOT_CRYPT" - -# LUKS2 header reservation. cryptsetup shifts the data down by this much to -# make room, so the filesystem must be shrunk by at least as much first. -HEADER_MIB=32 - -# Free space left in the filesystem when it is shrunk ahead of the conversion -# (rootdev mode only — see shrink_for_conversion). The grow runs immediately -# afterwards in the same boot, so this only has to cover the case where power is -# lost in between: the board comes up on the shrunk filesystem and has to be -# able to run until the next boot grows it back. -SHRINK_HEADROOM_MIB=1024 - -# ── Cipher ─────────────────────────────────────────────────────────────────── -# Chosen by whichever installer ran — packaging/luks/install.sh reads the SoC -# off the board it is running on, image/scripts/60-luks.sh knows the device -# class at build time — and applied HERE, possibly months later. -# -# Read only on the conversion path. Once the container exists its LUKS2 header -# records its own cipher and cryptsetup uses that, so a board whose config file -# is later changed or lost still unlocks normally. There is deliberately no -# fallback default: a wrong guess here is a board that either runs slow forever -# or fails to convert after it has already burned its OTP. -MB_LUKS_CONF="${MB_LUKS_CONF:-/etc/musallahboard/luks.conf}" - -# How much unused tail the card may have before the partition is considered -# worth growing. Not zero: partition tables align to megabyte boundaries, so an -# exact comparison would mean the grow runs on every single boot forever. -GROW_SLACK_MIB=64 - -# Everything goes to the console as well as the log. A board doing a -# twenty-minute reencrypt with a blank screen looks identical to a bricked one, -# and somebody will pull the power. -say() { - echo "[musallahboard-luks] $*" - echo "[musallahboard-luks] $*" >> /dev/console 2>/dev/null || true -} - -bail() { - say "ERROR: $*" - say "leaving the root filesystem untouched" - exit 0 -} - -# ── Opt-in ─────────────────────────────────────────────────────────────────── -ENABLED=0 -MB_ROOTDEV="" -DRY_RUN=0 -for x in $(cat /proc/cmdline); do - case "$x" in - mb_encrypt=1) ENABLED=1 ;; - mb_rootdev=*) MB_ROOTDEV="${x#mb_rootdev=}" ;; - mb_otp_dryrun=1) DRY_RUN=1 ;; - esac -done - -# ── Rehearsal mode ─────────────────────────────────────────────────────────── -# Swaps the SoC's one-time-programmable memory for a file baked into the -# initramfs by the hook, so that a real board can run the real conversion -# without spending its one permanent write. musallahboard-otp-key implements -# both sides of this; here it is only switched on. -# -# Announced on every boot, deliberately loudly. A board left in this state is -# encrypted with a key that anyone holding the card can read straight off the -# boot partition, and the only thing standing between that and someone -# believing the board is protected is this message. -if [ "$DRY_RUN" = "1" ]; then - MB_OTP_DRY_RUN=1 - MB_OTP_DRY_RUN_FILE=/etc/musallahboard/otp-dry-run.key - export MB_OTP_DRY_RUN MB_OTP_DRY_RUN_FILE - say "***********************************************************" - say "* REHEARSAL MODE — the disk key comes from a file in the *" - say "* initramfs, NOT from this SoC's OTP. This board is NOT *" - say "* protected. Reflash it before putting it on a wall. *" - say "***********************************************************" -fi - -if [ "$ENABLED" != "1" ]; then - say "mb_encrypt=1 not set — encryption is not enabled for this image" - exit 0 -fi - -# ── Device discovery ───────────────────────────────────────────────────────── -# Sets MODE, and DEV: the partition this script operates on. In by-slot mode DEV -# is left empty and the two symlinks are consulted directly, because there the -# plaintext and encrypted forms are genuinely two different names. - -# Resolve a mb_rootdev= tag to a block device. Prefers the udev symlink, which -# is what exists on a normally-booting board, and falls back to blkid for the -# case where udev has not produced it — a slow controller, or a rule that did -# not fire. -resolve_tag() { - _tag="$1" - _path="" - - case "$_tag" in - PARTUUID=*) - _path="/dev/disk/by-partuuid/${_tag#PARTUUID=}" - ;; - /dev/*) - _path="$_tag" - ;; - UUID=*|LABEL=*) - # Refused deliberately. Both name the FILESYSTEM. After the - # conversion the filesystem is inside the container and the - # partition reports the LUKS header's own UUID instead, so this - # would resolve on the boot that encrypts the board and never - # again. The installer translates to PARTUUID for this reason. - say "mb_rootdev=${_tag} names a filesystem, not a partition." - say "It would stop resolving the moment this board is encrypted." - return 1 - ;; - *) - say "mb_rootdev=${_tag} is not a form this script understands" - return 1 - ;; - esac - - # initramfs-tools starts udev and settles it during init-top, so this is - # normally present the instant this runs. Normally. An SD card behind a slow - # controller can enumerate after settle returns, and the failure mode of not - # waiting is a board that skips its own encryption because the device was - # one second late. - _i=0 - while [ "$_i" -lt 30 ]; do - [ -b "$_path" ] && break - [ "$_i" -eq 0 ] && say "waiting for ${_path}" - sleep 1 - _i=$(( _i + 1 )) - done - - if [ ! -b "$_path" ]; then - case "$_tag" in - PARTUUID=*) - _path="$(blkid -t "$_tag" -o device 2>/dev/null | head -n1)" - ;; - esac - fi - - [ -n "$_path" ] && [ -b "$_path" ] || return 1 - readlink -f "$_path" -} - -DEV="" -if [ -n "$MB_ROOTDEV" ]; then - MODE="rootdev" - DEV="$(resolve_tag "$MB_ROOTDEV")" \ - || bail "cannot resolve mb_rootdev=${MB_ROOTDEV}" - say "root partition: ${DEV} (from mb_rootdev=${MB_ROOTDEV})" -else - MODE="byslot" - # Same wait, for the same reason, against whichever of the two names the - # board is going to present this boot. - i=0 - while [ "$i" -lt 30 ]; do - [ -b "$BY_SLOT_CRYPT" ] || [ -b "$BY_SLOT_SYSTEM" ] && break - [ "$i" -eq 0 ] && say "waiting for the root device to appear" - sleep 1 - i=$(( i + 1 )) - done -fi - -# ── Partition geometry helpers ─────────────────────────────────────────────── -# Read from sysfs rather than by shelling out to a partition tool: sysfs is -# always there, needs no extra binary, and reports the kernel's own view rather -# than a possibly stale on-disk table. -# -# Partition device names are not derivable by string manipulation — the same -# disk is mmcblk0p2, nvme0n1p2 or sda2 depending on the medium — so the disk -# and the partition number both come from sysfs too. -DISK_DEV="" -PART_NUM="" -TAIL_SECTORS=0 -PART_SECTORS=0 - -read_geometry() { - _dev="$1" - _sys="/sys/class/block/$(basename "$_dev")" - [ -d "$_sys" ] || return 1 - [ -r "${_sys}/partition" ] || return 1 - - _disk_sys="$(dirname "$(readlink -f "$_sys")")" - [ -r "${_sys}/start" ] && [ -r "${_sys}/size" ] && [ -r "${_disk_sys}/size" ] || return 1 - - PART_NUM="$(cat "${_sys}/partition")" - DISK_DEV="/dev/$(basename "$_disk_sys")" - - _start=$(cat "${_sys}/start") - PART_SECTORS=$(cat "${_sys}/size") - _disk=$(cat "${_disk_sys}/size") - TAIL_SECTORS=$(( _disk - _start - PART_SECTORS )) - return 0 -} - -# Grow the root partition to the end of the card. Idempotent by design: it is -# called on every boot, and does nothing once the tail is smaller than the -# slack. That matters because power can be lost between the reencryption and -# the grow, and the next boot has to finish the job rather than leave the board -# running on a partition a fraction of the card's size forever. -grow_partition() { - _dev="$1" - read_geometry "$_dev" || { say "WARNING: cannot read partition geometry — not growing"; return 1; } - - _slack=$(( GROW_SLACK_MIB * 1024 * 1024 / 512 )) - if [ "$TAIL_SECTORS" -le "$_slack" ]; then - return 1 - fi - - say "growing partition ${PART_NUM} to fill the card ($(( TAIL_SECTORS / 2048 )) MiB unused)" - - # ",+" means: keep the start where it is, take all remaining space. sfdisk - # updates the kernel's view through BLKPG for the one partition it changed, - # which is what makes this safe to do to a device that is already open. - if ! echo ',+' | sfdisk --no-reread --force -N "$PART_NUM" "$DISK_DEV" >> /dev/console 2>&1; then - say "WARNING: sfdisk failed — the card will be usable but not fully" - return 1 - fi - - # Belt and braces for kernels or media where BLKPG did not take. - partx -u "$DISK_DEV" >/dev/null 2>&1 || true - udevadm settle >/dev/null 2>&1 || true - return 0 -} - -# ── Shrink before encrypting (rootdev mode only) ───────────────────────────── -# An rpi-image-gen image ships a partition barely larger than its contents and -# grows AFTER encrypting, so its one-time reencryption cost is a few gigabytes -# whatever card it was flashed to. A bare-metal Raspberry Pi OS install has -# already expanded its root to fill the card by the time the installer runs, so -# without this the same conversion rewrites the entire card: hours on a 128 GB -# one, in front of a person who has been told not to power it off. -# -# So: shrink the filesystem to what it actually needs, shrink the partition to -# match, encrypt that, and let the existing grow_partition put it all back. Both -# halves already existed; this is the mirror image of the grow. -# -# Every failure here is non-fatal and falls through to encrypting the partition -# at full size. That is slow, and it is correct, which is the right way round. -shrink_for_conversion() { - _dev="$1" - - _blk=$(tune2fs -l "$_dev" 2>/dev/null | awk '/^Block size:/ {print $3}') - [ -n "$_blk" ] || { say "WARNING: cannot read block size — not shrinking"; return 1; } - - # -P estimates the minimum without touching anything. resize2fs -M would - # shrink to exactly that, which leaves a filesystem with no room to boot on - # if power is lost before the grow. - _min=$(resize2fs -P "$_dev" 2>/dev/null | awk -F': *' '/minimum size/ {print $2}') - case "$_min" in - ''|*[!0-9]*) say "WARNING: cannot estimate minimum size — not shrinking"; return 1 ;; - esac - - _target=$(( _min + SHRINK_HEADROOM_MIB * 1024 * 1024 / _blk )) - - read_geometry "$_dev" || { say "WARNING: cannot read partition geometry — not shrinking"; return 1; } - - # Sectors the shrunk partition needs: the filesystem plus the header the - # reencryption is about to reserve at the front. - _want_sectors=$(( _target * (_blk / 512) + HEADER_MIB * 1024 * 1024 / 512 )) - - # Nothing to gain. Leave a generous margin — shrinking to save a few hundred - # megabytes is all risk and no benefit. - if [ "$_want_sectors" -ge $(( PART_SECTORS - 512 * 1024 * 2 )) ]; then - say "partition is already close to the filesystem size — not shrinking" - return 1 - fi - - say "shrinking filesystem to $(( _target * _blk / 1024 / 1024 )) MiB before encrypting" - say "(partition is $(( PART_SECTORS / 2048 )) MiB — encrypting all of it would take far longer)" - - if ! resize2fs "$_dev" "$_target" >> /dev/console 2>&1; then - say "WARNING: could not shrink the filesystem — encrypting at full size" - return 1 - fi - - if ! echo ",${_want_sectors}" | sfdisk --no-reread --force -N "$PART_NUM" "$DISK_DEV" >> /dev/console 2>&1; then - # The filesystem is smaller than the partition now, which is a perfectly - # valid state — the reencryption just has more to chew through. - say "WARNING: could not shrink the partition — encrypting at full size" - return 1 - fi - - partx -u "$DISK_DEV" >/dev/null 2>&1 || true - udevadm settle >/dev/null 2>&1 || true - say "partition shrunk to $(( _want_sectors / 2048 )) MiB for the conversion" - return 0 -} - -# ── Which state are we in? ─────────────────────────────────────────────────── -# by-slot mode asks which of the two names exists; rootdev mode asks the one -# device whether it is already a container. -IS_ENCRYPTED=0 -if [ "$MODE" = "rootdev" ]; then - if cryptsetup isLuks "$DEV" 2>/dev/null; then - IS_ENCRYPTED=1 - fi -else - if [ -b "$BY_SLOT_CRYPT" ]; then - IS_ENCRYPTED=1 - DEV="$(readlink -f "$BY_SLOT_CRYPT")" - [ -b "$DEV" ] || bail "cannot resolve ${BY_SLOT_CRYPT}" - fi -fi - -# ── State 1: already encrypted ─────────────────────────────────────────────── -if [ "$IS_ENCRYPTED" = "1" ]; then - if [ -b "$MAPPER" ]; then - exit 0 - fi - - # A reencryption interrupted by power loss leaves resume metadata in the - # LUKS2 header. This must be handled before anything tries to open or mount - # the device: the filesystem is a mix of encrypted and plaintext extents - # until it finishes, and mounting it in that state destroys it. - if cryptsetup luksDump "$DEV" 2>/dev/null | grep -qi 'reencrypt'; then - say "interrupted reencryption detected — resuming (do NOT power off)" - if ! musallahboard-otp-key --print > /run/mb.key 2>/dev/null; then - bail "cannot derive key to resume reencryption" - fi - cryptsetup reencrypt --resume-only --key-file /run/mb.key \ - --progress-frequency 10 "$DEV" >> /dev/console 2>&1 - rc=$? - rm -f /run/mb.key - [ "$rc" -eq 0 ] || bail "resume failed (rc=${rc})" - say "reencryption resumed and completed" - fi - - # Growing before opening, not after: the partition is not yet backing a - # device-mapper target, so there is nothing holding it. - grow_partition "$DEV" && GREW=1 || GREW=0 - - say "unlocking root filesystem" - if ! musallahboard-otp-key --print > /run/mb.key 2>/dev/null; then - bail "could not derive the disk key from OTP" - fi - if ! cryptsetup open --type luks --key-file /run/mb.key "$DEV" "$MAPPER_NAME"; then - rm -f /run/mb.key - # Deliberately not a retry loop or a passphrase prompt. If the - # OTP-derived key does not open this container, the card is in a - # different Pi than the one it was encrypted on — which is exactly the - # case this design exists to refuse. - panic "musallahboard: root filesystem cannot be unlocked on this board." - fi - - if [ "$GREW" = "1" ]; then - say "expanding the encrypted volume into the grown partition" - cryptsetup resize --key-file /run/mb.key "$MAPPER_NAME" >> /dev/console 2>&1 \ - || say "WARNING: could not resize the LUKS mapping" - e2fsck -fy "$MAPPER" >> /dev/console 2>&1 || true - resize2fs "$MAPPER" >> /dev/console 2>&1 \ - || say "WARNING: could not grow the filesystem" - fi - - rm -f /run/mb.key - udevadm settle >/dev/null 2>&1 || true - say "unlocked" - exit 0 -fi - -# ── State 2: convert ───────────────────────────────────────────────────────── -if [ "$MODE" = "byslot" ]; then - [ -b "$BY_SLOT_SYSTEM" ] || bail "neither ${BY_SLOT_CRYPT} nor ${BY_SLOT_SYSTEM} exists" - - DEV="$(readlink -f "$BY_SLOT_SYSTEM")" - [ -b "$DEV" ] || bail "cannot resolve ${BY_SLOT_SYSTEM}" - - # by-slot/system resolving to something that is already LUKS would mean a - # container whose label never got set. Refusing is right: converting it a - # second time would encrypt ciphertext. - if cryptsetup isLuks "$DEV" 2>/dev/null; then - bail "${DEV} is already a LUKS container but is not labelled ${CRYPT_LABEL}" - fi -fi - -[ -b "$DEV" ] || bail "no root device to convert" - -# The cipher, read before anything irreversible happens. Doing this after the -# OTP burn would mean a board that has permanently spent its one write and then -# discovered it does not know how to encrypt itself. -if [ -r "$MB_LUKS_CONF" ]; then - . "$MB_LUKS_CONF" -fi -case "${MB_LUKS_CIPHER:-}" in - ?*) : ;; - *) bail "no cipher configured (${MB_LUKS_CONF} missing or empty) — NOT encrypting" ;; -esac -case "${MB_LUKS_KEYSIZE:-}" in - 128|256|512) : ;; - *) bail "invalid key size '${MB_LUKS_KEYSIZE:-}' in ${MB_LUKS_CONF} — NOT encrypting" ;; -esac - -say "════════════════════════════════════════════════════════" -say " ENCRYPTING THE ROOT FILESYSTEM" -say " cipher: ${MB_LUKS_CIPHER} (${MB_LUKS_KEYSIZE}-bit)" -say " This runs once and takes a few minutes. DO NOT POWER OFF." -say " (If power is lost, the next boot resumes where it stopped.)" -say "════════════════════════════════════════════════════════" - -modprobe dm_mod 2>/dev/null || true -modprobe dm_crypt 2>/dev/null || true - -# THE OTP BURN. Permanent, and the point of no return for this board. -if ! musallahboard-otp-key --ensure > /run/mb.key 2>>/dev/console; then - rm -f /run/mb.key - bail "could not obtain a device key from OTP — NOT encrypting" -fi -[ -s /run/mb.key ] || { rm -f /run/mb.key; bail "derived key is empty"; } - -say "checking filesystem" -e2fsck -fy "$DEV" >> /dev/console 2>&1 || true - -# On bare metal the partition already fills the card, so cut it down to the data -# before encrypting rather than after. Skipped in by-slot mode, where the image -# was built small on purpose and this would be a no-op with a partition editor -# in it. -if [ "$MODE" = "rootdev" ]; then - shrink_for_conversion "$DEV" || true -fi - -# Make room for the LUKS2 header by shrinking the filesystem to fit within -# (partition - 32 MiB). After shrink_for_conversion this is usually already -# true and resize2fs is a no-op; in by-slot mode, or when the shrink declined, -# it is what makes the reencryption possible at all. -blk_size=$(tune2fs -l "$DEV" | awk '/^Block size:/ {print $3}') -dev_bytes=$(blockdev --getsize64 "$DEV") -[ -n "$blk_size" ] && [ -n "$dev_bytes" ] || { rm -f /run/mb.key; bail "cannot size the filesystem"; } - -target_blocks=$(( (dev_bytes - HEADER_MIB * 1024 * 1024) / blk_size )) -say "resizing filesystem to make room for the LUKS header" -if ! resize2fs "$DEV" "$target_blocks" >> /dev/console 2>&1; then - rm -f /run/mb.key - bail "could not resize the filesystem — NOT encrypting" -fi - -# --pbkdf pbkdf2 with the minimum iteration count, on purpose. The passphrase is -# a SHA-256 digest of 256 bits of hardware randomness, not something a person -# typed, so there is nothing for a slow KDF to protect: brute force is already -# off the table. What argon2id WOULD do here is try to allocate up to 1 GB -# inside an initramfs on a 2 GB Pi 4B, and get OOM-killed halfway through -# converting the root filesystem. -# -# --label is what makes the by-slot udev rule fire on subsequent boots, and what -# identifies the card to a human in either mode. It is asserted immediately -# below rather than trusted. -say "starting reencryption" -if ! cryptsetup reencrypt --encrypt \ - --type luks2 \ - --reduce-device-size "${HEADER_MIB}M" \ - --cipher "$MB_LUKS_CIPHER" \ - --key-size "$MB_LUKS_KEYSIZE" \ - --label "$CRYPT_LABEL" \ - --pbkdf pbkdf2 \ - --pbkdf-force-iterations 1000 \ - --batch-mode \ - --progress-frequency 10 \ - --key-file /run/mb.key \ - "$DEV" >> /dev/console 2>&1; then - rm -f /run/mb.key - bail "reencryption failed — the next boot will retry or resume" -fi -say "reencryption complete" - -# In by-slot mode the label is not cosmetic: without it there is no -# by-slot/cryptroot, this script finds nothing on the next boot, and the board -# sits at an initramfs prompt with a perfectly good encrypted filesystem in -# front of it. Older cryptsetup builds ignore --label on reencrypt, so set it -# again explicitly and only then check. -cryptsetup config --label "$CRYPT_LABEL" "$DEV" >/dev/null 2>&1 || true -if ! cryptsetup luksDump "$DEV" 2>/dev/null | grep -q "$CRYPT_LABEL"; then - if [ "$MODE" = "byslot" ]; then - rm -f /run/mb.key - bail "container is encrypted but has no ${CRYPT_LABEL} label — fix with: cryptsetup config --label ${CRYPT_LABEL} ${DEV}" - fi - # In rootdev mode discovery is by PARTUUID, which is untouched by all of - # this, so a missing label costs identification convenience and nothing else. - say "WARNING: container has no ${CRYPT_LABEL} label (harmless in this mode)" -fi - -# Now take the rest of the card. -grow_partition "$DEV" || true - -if ! cryptsetup open --type luks --key-file /run/mb.key "$DEV" "$MAPPER_NAME"; then - rm -f /run/mb.key - bail "encrypted the filesystem but cannot reopen it" -fi - -cryptsetup resize --key-file /run/mb.key "$MAPPER_NAME" >> /dev/console 2>&1 \ - || say "WARNING: could not resize the LUKS mapping" -rm -f /run/mb.key - -e2fsck -fy "$MAPPER" >> /dev/console 2>&1 || true -resize2fs "$MAPPER" >> /dev/console 2>&1 || say "WARNING: could not grow the filesystem" - -# No reboot, and nothing to rewrite. The state on disk is now exactly the state -# every subsequent boot will find: in by-slot mode because -# root=/dev/disk/by-slot/system resolves to the open mapper via the DM branch of -# the storage-binder rules, and in rootdev mode because the installer already -# pointed root= at /dev/mapper/musallahroot from a running system. Neither one -# edits a boot file from inside an initramfs. -udevadm settle >/dev/null 2>&1 || true - -if [ -b "$MAPPER" ]; then - say "encryption complete — continuing boot" - exit 0 -fi - -bail "mapper did not appear after conversion" diff --git a/packaging/luks/install.sh b/packaging/luks/install.sh deleted file mode 100644 index 1c3844d..0000000 --- a/packaging/luks/install.sh +++ /dev/null @@ -1,641 +0,0 @@ -#!/bin/bash -# ===================================================== -# packaging/luks/install.sh — OTP-keyed root encryption, on a running board -# ===================================================== -# Turns a booted Raspberry Pi OS install into one that encrypts its own root -# filesystem on the next boot, keyed to a secret burned into this specific SoC's -# one-time-programmable memory. -# -# Nothing is encrypted HERE. This script installs the tooling, proves the -# initramfs can actually do the job, and only then points the boot files at the -# encrypted device. The conversion itself happens on the next boot, in the -# initramfs, where the root filesystem is not mounted. See initramfs-local-top. -# -# --no-encrypt install the tooling but leave the boot files alone. The -# hook is inert. Safe, and re-runnable. -# --dry-run-otp rehearse the entire conversion on this board against a file -# that stands in for OTP. BURNS NOTHING. The resulting board -# is encrypted but NOT protected — see the warning it prints. -# --yes skip the confirmation prompt (fleet provisioning). -# -# Called from setup.sh's platform_after_hardening, or by hand. -# ===================================================== -set -euo pipefail - -SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" - -MB_ENCRYPT=1 -DRY_RUN_OTP=0 -ASSUME_YES=0 - -MAPPER_NAME="musallahroot" -MAPPER="/dev/mapper/${MAPPER_NAME}" -FW=/boot/firmware -CMDLINE="${FW}/cmdline.txt" -CONFIG="${FW}/config.txt" -DRY_RUN_KEY=/etc/musallahboard/otp-dry-run.key - -for arg in "$@"; do - case "$arg" in - --encrypt) MB_ENCRYPT=1 ;; - --no-encrypt) MB_ENCRYPT=0 ;; - --dry-run-otp) DRY_RUN_OTP=1 ;; - --yes|-y) ASSUME_YES=1 ;; - *) echo "FATAL: unknown argument: $arg"; exit 1 ;; - esac -done - -die() { echo "FATAL: $*" >&2; exit 1; } - -# ── Preflight ──────────────────────────────────────────────────────────────── -[ "$(id -u)" -eq 0 ] || die "must run as root" -[ -d "$SRC" ] || die "$SRC missing" - -# Uploaded from a Windows checkout by way of a release tarball. The three -# payload files are extensionless, so they rely on .gitattributes rather than -# the *.sh rule — strip CRs anyway rather than trust that. A CR in the shebang -# of the local-top script makes the initramfs look for "/bin/sh\r". -sed -i 's/\r$//' "${SRC}/musallahboard-otp-key" "${SRC}/initramfs-hook" "${SRC}/initramfs-local-top" - -[ "$(uname -m)" = "aarch64" ] || die "this is a 64-bit arm64 image only (got $(uname -m))" -[ -f "$CMDLINE" ] || die "${CMDLINE} missing — is this Raspberry Pi OS?" -[ -f "$CONFIG" ] || die "${CONFIG} missing — is this Raspberry Pi OS?" - -# ── Which SoC ──────────────────────────────────────────────────────────────── -# The device tree is the authority. /proc/cpuinfo's Revision field would work -# too but needs a lookup table that has to be maintained; `compatible` names the -# chip directly. -COMPAT="$(tr -d '\0' < /proc/device-tree/compatible 2>/dev/null || true)" -MODEL="$(tr -d '\0' < /proc/device-tree/model 2>/dev/null || echo unknown)" - -echo "═══ board ═══" -echo " ${MODEL}" - -# ── Cipher ─────────────────────────────────────────────────────────────────── -# BCM2711 — the Pi 4B's SoC — does not implement the ARMv8 cryptography -# extensions. There is no AES instruction on a Cortex-A72, so aes-xts-plain64 -# there runs entirely in software and competes with Chromium for the same four -# cores. BCM2712 (Cortex-A76, Pi 5) does have them and AES is the right choice. -# -# Adiantum is what exists for this case: a length-preserving construction built -# on XChaCha12 and NH, designed for exactly the CPUs that have no AES -# acceleration, and what Android uses on low-end hardware for the same reason. -# -# This is not our opinion. It is the same split Raspberry Pi's own rpi-idp-luks2 -# layer encodes. -# -# Unlike the image build, which has to decide this months before the board sees -# it, here the SoC is sitting right there and can simply be asked. -case "$COMPAT" in - *bcm2712*) - LUKS_CIPHER="aes-xts-plain64" - LUKS_KEYSIZE=512 - CIPHER_WHY="BCM2712 has the ARMv8 crypto extensions" - ;; - *bcm2711*) - LUKS_CIPHER="xchacha12,aes-adiantum-plain64" - LUKS_KEYSIZE=256 - CIPHER_WHY="BCM2711 has no AES instruction — software AES would cost the CPU" - ;; - *) - # Refusing rather than defaulting. Defaulting to AES on an unknown SoC - # silently ships a slow board; defaulting to Adiantum on one that has - # AES silently ships a slower-than-necessary one. Both are the kind of - # thing nobody notices for a year. - echo "FATAL: unrecognised SoC." - echo " device-tree compatible: ${COMPAT:-(none)}" - echo " Supported: Raspberry Pi 4 / CM4 (BCM2711) and Pi 5 / CM5 (BCM2712)." - echo " Add the SoC to the cipher table in this script rather than" - echo " picking a cipher for it by hand." - exit 1 - ;; -esac - -# ── Where is root, and is there anything to do? ────────────────────────────── -ROOT_SRC="$(findmnt -no SOURCE / )" -ROOT_FSTYPE="$(findmnt -no FSTYPE / )" - -if [ "$ROOT_SRC" = "$MAPPER" ]; then - echo "═══ already encrypted ═══" - echo " / is ${MAPPER}. Nothing to do." - exit 0 -fi - -[ "$ROOT_FSTYPE" = "ext4" ] \ - || die "root filesystem is ${ROOT_FSTYPE}, and the conversion is ext4-only (it uses resize2fs)" - -# PARTUUID, not UUID or LABEL. It lives in the partition table, which the -# conversion never touches, so it resolves identically before and after. A -# filesystem UUID moves inside the container the moment the board is encrypted -# and would resolve exactly once — see the note in initramfs-local-top. -ROOT_PARTUUID="$(blkid -s PARTUUID -o value "$ROOT_SRC" 2>/dev/null || true)" -[ -n "$ROOT_PARTUUID" ] \ - || die "${ROOT_SRC} has no PARTUUID — cannot describe it in a way that survives encryption" - -echo "═══ root filesystem ═══" -echo " device : ${ROOT_SRC}" -echo " PARTUUID : ${ROOT_PARTUUID}" -echo " size : $(( $(blockdev --getsize64 "$ROOT_SRC") / 1024 / 1024 )) MiB" - -# ── Packages ───────────────────────────────────────────────────────────────── -# rpi-eeprom ships /usr/bin/rpi-otp-private-key and raspi-utils-core ships -# /usr/bin/vcmailbox. Between them they are the entire path to the OTP secret -# the disk key is derived from. -# -# Most documentation, including Raspberry Pi's own, still says vcmailbox comes -# from libraspberrypi-bin. That package does not exist for arm64 trixie at all — -# the utilities were split into raspi-utils-* — and naming it here is not a -# harmless extra: apt fails with "no installation candidate". -# -# DEBIAN_FRONTEND is not decoration: installing initramfs-tools on a system that -# does not already have it opens a debconf prompt about initramfs.conf, and this -# script is routinely run down a pipe where there is nobody to answer it. -echo "═══ packages ═══" -export DEBIAN_FRONTEND=noninteractive -apt-get update -qq -apt-get install -y -qq --no-install-recommends \ - cryptsetup \ - cryptsetup-bin \ - fdisk \ - e2fsprogs \ - initramfs-tools \ - rpi-eeprom \ - raspi-utils-core - -for t in cryptsetup sfdisk resize2fs tune2fs e2fsck blkid vcmailbox rpi-otp-private-key; do - command -v "$t" >/dev/null || die "${t} missing after package install" - echo " $(command -v "$t")" -done -echo " $(cryptsetup --version)" - -# ── Key derivation ─────────────────────────────────────────────────────────── -echo "═══ installing key derivation ═══" -install -o root -g root -m 0755 "${SRC}/musallahboard-otp-key" \ - /usr/local/sbin/musallahboard-otp-key -sh -n /usr/local/sbin/musallahboard-otp-key -echo " /usr/local/sbin/musallahboard-otp-key" - -install -d -m 0755 /etc/musallahboard -cat > /etc/musallahboard/luks.conf < "$DRY_RUN_KEY" - chmod 0600 "$DRY_RUN_KEY" - echo " ${DRY_RUN_KEY} — this board's OTP will NOT be touched" -else - # Report the OTP state without changing it. A board whose OTP is already - # programmed is fine — it is either a re-run or a board that has been - # through this before, and the same key derives from it either way. - echo "═══ OTP ═══" - if OTP_STATE="$(musallahboard-otp-key --status 2>/dev/null)"; then - echo " ${OTP_STATE} — the existing device key will be reused" - else - echo " blank — a device key will be generated and burned on the next boot" - fi -fi - -# ── Initramfs integration ──────────────────────────────────────────────────── -echo "═══ installing initramfs integration ═══" -install -d -m 0755 /etc/initramfs-tools/hooks /etc/initramfs-tools/scripts/local-top -install -o root -g root -m 0755 "${SRC}/initramfs-hook" \ - /etc/initramfs-tools/hooks/musallahboard-luks -install -o root -g root -m 0755 "${SRC}/initramfs-local-top" \ - /etc/initramfs-tools/scripts/local-top/musallahboard-luks -sh -n /etc/initramfs-tools/hooks/musallahboard-luks -sh -n /etc/initramfs-tools/scripts/local-top/musallahboard-luks -echo " hook + local-top installed, syntax OK" - -# ── auto_initramfs ─────────────────────────────────────────────────────────── -# Without this the firmware loads the kernel directly and the local-top script -# never runs — which, once the boot files point at the mapper, is a board that -# does not boot. -# -# auto_initramfs rather than a hardcoded `initramfs initramfs8 followkernel` -# line: it makes the firmware pick up whatever update-initramfs regenerated -# after a kernel upgrade. The hardcoded form goes stale the first time apt -# installs a new kernel. -# -# config.txt is sectioned ([pi4], [pi5], [all], ...) and a bare append lands in -# whichever section happens to be last — which on some templates is a -# model-specific one, so the setting silently applies to one board and not the -# other. Ours goes into an explicit [all] block. -echo "═══ auto_initramfs ═══" -if grep -qE '^[[:space:]]*auto_initramfs=1' "$CONFIG"; then - echo " already set" -else - cp -a "$CONFIG" "${CONFIG}.mb-orig" - cat >> "$CONFIG" <<'EOF' - -[all] -# ── MusallahBoard ── -# The root filesystem is unlocked by a script in the initramfs. Without this -# the firmware boots the kernel directly and that script never runs. -auto_initramfs=1 -EOF - echo " added (original saved as ${CONFIG}.mb-orig)" -fi - -# ── Which kernels ──────────────────────────────────────────────────────────── -KERNELS=() -for d in /lib/modules/*/; do - v="$(basename "$d")" - # Skip module trees with no kernel image to match; update-initramfs fails on - # those and would take the whole run down with it. - [ -d "${d}kernel" ] || continue - KERNELS+=("$v") -done -[ "${#KERNELS[@]}" -gt 0 ] || die "no kernel module trees under /lib/modules" - -# ── Can this kernel actually do the chosen cipher? ─────────────────────────── -# Checked BEFORE building anything, because it is the cheapest possible place to -# find out, and because the failure it prevents is the most expensive one -# available: a kernel with no Adiantum produces an initramfs that looks -# complete, and the Pi 4 that boots it reaches the reencryption, BURNS ITS OTP, -# and only then discovers it cannot create the container. That burn is -# permanent. -# -# Checked against modules.builtin as well as the module tree, because a cipher -# compiled into the kernel is legitimately absent from both /lib/modules and the -# initramfs. Treating that as a failure would block a perfectly good board. -# -# Each entry is a set of acceptable names separated by |. Module naming moves -# between kernel versions and arm64 ships accelerated variants under their own -# names, so a single spelling is not something to bet a fleet's boot path on. -case "$LUKS_CIPHER" in - aes-xts-plain64) - CRYPTO_REQ=( - "xts" - "aes|aes_generic|aes-ce-blk|aes-neon-blk|aes-neon-bs|aes-arm64" - ) - ;; - xchacha12,aes-adiantum-plain64) - CRYPTO_REQ=( - "adiantum" - "nhpoly1305|nhpoly1305-neon" - "chacha|chacha_generic|chacha-neon|chacha-neon-arm64|libchacha" - "poly1305|poly1305_generic|poly1305-neon" - "aes|aes_generic|aes-ce-blk|aes-neon-blk|aes-neon-bs|aes-arm64" - ) - ;; -esac - -MODWANT=() -FAILED=0 - -echo "═══ kernel support for ${LUKS_CIPHER} ═══" -for v in "${KERNELS[@]}"; do - BUILTIN_LIST="/lib/modules/${v}/modules.builtin" - for req in "${CRYPTO_REQ[@]}"; do - found="" - kind="" - IFS='|' read -ra alts <<< "$req" - for m in "${alts[@]}"; do - if grep -qE "/${m}\.ko" "$BUILTIN_LIST" 2>/dev/null; then - found="$m"; kind="builtin"; break - fi - if find "/lib/modules/${v}" -name "${m}.ko*" -print -quit 2>/dev/null | grep -q .; then - found="$m"; kind="module"; break - fi - done - - case "$kind" in - builtin) - printf ' \033[0;32mok\033[0m %s (built into %s)\n' "$found" "$v" - ;; - module) - # Loadable: must be pulled into the initramfs, because the root - # filesystem it would otherwise load from is the thing being - # encrypted. - MODWANT+=("/${found}.ko") - printf ' \033[0;32mok\033[0m %s (module in %s)\n' "$found" "$v" - ;; - *) - printf ' \033[0;31mFAIL\033[0m none of {%s} in %s\n' "${req//|/, }" "$v" - FAILED=1 - ;; - esac - done -done -[ "$FAILED" -eq 0 ] || { - echo "FATAL: this kernel cannot do ${LUKS_CIPHER}." - echo " For this SoC that cipher is not a preference — see the cipher" - echo " note in this script. Do not switch to aes-xts-plain64 to get" - echo " past this without reading it first." - exit 1 -} - -# ── Build ──────────────────────────────────────────────────────────────────── -echo "═══ building initramfs ═══" -STARTED_AT="$(date +%s)" -for v in "${KERNELS[@]}"; do - echo " ── ${v} ──" - update-initramfs -u -k "$v" 2>&1 | sed 's/^/ /' \ - || update-initramfs -c -k "$v" 2>&1 | sed 's/^/ /' \ - || die "update-initramfs failed for ${v}" -done - -# ── Assert the initramfs actually contains what it needs ───────────────────── -# The hook exits non-zero on a missing tool, which fails update-initramfs — but -# only if the hook ran at all. This proves the result, not the intent. A board -# that boots an initramfs without cryptsetup skips encryption silently and -# reports success, which is the worst failure mode available here. -echo "═══ verifying initramfs contents ═══" - -WANT=( - sbin/cryptsetup - sfdisk - musallahboard-otp-key - rpi-otp-private-key - vcmailbox - sha256sum - resize2fs - blkid - scripts/local-top/musallahboard-luks - musallahboard/luks.conf -) -WANT+=("${MODWANT[@]}") -[ "$DRY_RUN_OTP" = "1" ] && WANT+=(musallahboard/otp-dry-run.key) - -for v in "${KERNELS[@]}"; do - IMG="/boot/initrd.img-${v}" - [ -f "$IMG" ] || { echo " FAIL: ${IMG} not produced"; FAILED=1; continue; } - - CONTENTS="$(lsinitramfs "$IMG" 2>/dev/null)" - for want in "${WANT[@]}"; do - if printf '%s\n' "$CONTENTS" | grep -q -- "$want"; then - printf ' \033[0;32mok\033[0m %s in initrd.img-%s\n' "$want" "$v" - else - printf ' \033[0;31mFAIL\033[0m %s MISSING from initrd.img-%s\n' "$want" "$v" - FAILED=1 - fi - done -done -[ "$FAILED" -eq 0 ] || { - echo "FATAL: the initramfs is missing required components." - echo " A missing .ko here means the module exists in /lib/modules but" - echo " did not get pulled into the initramfs — which for a crypto" - echo " module means the board could not create or open its own root." - exit 1 -} - -# ── Will the firmware actually load it? ────────────────────────────────────── -# This is the check that stands between a provisioned board and an unbootable -# one. With auto_initramfs=1 the firmware derives the initramfs filename from -# the kernel it loads: kernel8.img wants initramfs8, kernel_2712.img wants -# initramfs_2712, in the same directory. So the question is answerable exactly, -# by name, without knowing anything about which distribution hook was supposed -# to have done the copying. -echo "═══ boot partition ═══" -firmware_initramfs_for() { - # kernel8.img -> initramfs8 ; kernel_2712.img -> initramfs_2712 - _base="$(basename "$1")" - _suffix="${_base#kernel}" - _suffix="${_suffix%.img}" - printf '%s/initramfs%s' "$FW" "$_suffix" -} - -# Match a kernel image to the module tree it belongs to, so the right initrd -# gets copied if we end up having to do it ourselves. -initrd_for_suffix() { - case "$1" in - *2712*) _pat="2712" ;; - *) _pat="v8" ;; - esac - for _v in "${KERNELS[@]}"; do - case "$_v" in - *"$_pat"*) [ -f "/boot/initrd.img-${_v}" ] && { printf '/boot/initrd.img-%s' "$_v"; return 0; } ;; - esac - done - return 1 -} - -MISSING_FW=0 -shopt -s nullglob -KERNEL_IMGS=("${FW}"/kernel*.img) -shopt -u nullglob -[ "${#KERNEL_IMGS[@]}" -gt 0 ] || die "no kernel*.img in ${FW} — cannot tell what the firmware will load" - -for kimg in "${KERNEL_IMGS[@]}"; do - want_fw="$(firmware_initramfs_for "$kimg")" - if [ -f "$want_fw" ] && [ "$(stat -c %Y "$want_fw")" -ge "$STARTED_AT" ]; then - printf ' \033[0;32mok\033[0m %s -> %s (fresh)\n' "$(basename "$kimg")" "$(basename "$want_fw")" - continue - fi - - # Nothing copied it, or what is there is stale. Do it here, and install a - # post-update hook so the next kernel upgrade does not silently undo it. - suffix="$(basename "$want_fw")" - if src_initrd="$(initrd_for_suffix "$suffix")"; then - cp -f "$src_initrd" "$want_fw" - printf ' \033[0;33mcopied\033[0m %s -> %s\n' "$(basename "$src_initrd")" "$(basename "$want_fw")" - else - printf ' \033[0;31mFAIL\033[0m no initrd matches %s\n' "$(basename "$want_fw")" - MISSING_FW=1 - fi -done - -if [ "$MISSING_FW" = "0" ] && [ ! -f /etc/initramfs/post-update.d/zz-musallahboard ]; then - # Only installed when the above had to intervene is tempting, but a hook - # that is idempotent and correct costs nothing and covers the case where - # this board's distribution hook disappears in a later upgrade. - install -d -m 0755 /etc/initramfs/post-update.d - cat > /etc/initramfs/post-update.d/zz-musallahboard <<'EOF' -#!/bin/sh -# Copy a regenerated initramfs to the boot partition under the name -# auto_initramfs=1 expects. Raspberry Pi OS normally does this itself; this runs -# after whatever did, writes the same bytes, and exists so that a board whose -# root filesystem is encrypted cannot be left with a stale initramfs it needs to -# boot. Idempotent by construction. -set -e -version="$1" -initrd="$2" -[ -n "$version" ] && [ -r "$initrd" ] || exit 0 - -case "$version" in - *2712*) suffix="_2712" ;; - *v8*) suffix="8" ;; - *) exit 0 ;; -esac - -target="/boot/firmware/initramfs${suffix}" -[ -d /boot/firmware ] || exit 0 -cp -f "$initrd" "$target" -sync -EOF - chmod 0755 /etc/initramfs/post-update.d/zz-musallahboard - echo " installed /etc/initramfs/post-update.d/zz-musallahboard" -fi - -[ "$MISSING_FW" -eq 0 ] || { - echo "FATAL: the firmware would not find an initramfs to load." - echo " Refusing to point the boot files at an encrypted device that" - echo " nothing would be able to unlock. Nothing has been changed." - exit 1 -} - -sync - -# ── Everything below this line changes how the board boots ─────────────────── -if [ "$MB_ENCRYPT" != "1" ]; then - echo - echo "═══ --no-encrypt ═══" - echo " Tooling installed and verified; boot files untouched." - echo " This board will boot exactly as it does now." - echo " Re-run without --no-encrypt to arm the conversion." - exit 0 -fi - -# ── Confirmation ───────────────────────────────────────────────────────────── -# Read from /dev/tty, not stdin. The documented way to run the installer is -# `curl … | sudo bash`, where stdin is the script itself — a `read` there -# consumes the rest of the script rather than an answer from a person. -confirm() { - [ "$ASSUME_YES" = "1" ] && return 0 - - if [ ! -r /dev/tty ]; then - echo "FATAL: no terminal to ask for confirmation on." - echo " Re-run with --yes if you mean it." - exit 1 - fi - - echo - echo " ╔══════════════════════════════════════════════════════════════╗" - if [ "$DRY_RUN_OTP" = "1" ]; then - echo " ║ REHEARSAL — nothing permanent happens ║" - echo " ╚══════════════════════════════════════════════════════════════╝" - echo - echo " The next boot will encrypt this board's root filesystem using a" - echo " key from a FILE, not from this SoC's OTP. The OTP is not touched." - echo - echo " The resulting board is NOT protected: the key sits in an" - echo " unencrypted initramfs on the FAT boot partition. Reflash it" - echo " before it goes anywhere near a wall." - else - echo " ║ THIS IS PERMANENT ║" - echo " ╚══════════════════════════════════════════════════════════════╝" - echo - echo " On the next boot this board will:" - echo - echo " 1. Burn a random 256-bit key into its OTP memory." - echo " Those bits go from 0 to 1 and NEVER back. There is no undo," - echo " no escrow, and no second attempt." - echo " 2. Encrypt its root filesystem in place with that key." - echo - echo " Afterwards:" - echo " • This card will only be readable by THIS board. Not by a" - echo " laptop, not by a card reader, not by another Pi." - echo " • If this board dies, its card is unrecoverable. Reflash and" - echo " re-enroll; nothing on it cannot be rebuilt from the backend." - echo - echo " If you have not rehearsed this yet, answer no and re-run with" - echo " --dry-run-otp first. It exercises all of the above and burns" - echo " nothing." - fi - echo - printf ' Type YES to continue: ' - read -r answer < /dev/tty - [ "$answer" = "YES" ] || { echo " Aborted. Nothing has been changed."; exit 1; } -} -confirm - -# ── Point the boot files at the encrypted device ───────────────────────────── -# Done here, from a running system, where the result can be read back and -# checked — not from inside an initramfs on a board nobody is looking at. The -# originals go next to them: cmdline.txt lives on the FAT boot partition, so a -# board that will not boot is recoverable by editing one file on any machine -# with a card reader. -echo "═══ boot configuration ═══" - -cp -a "$CMDLINE" "${CMDLINE}.mb-orig" -cp -a /etc/fstab /etc/fstab.mb-orig - -# cmdline.txt must remain exactly one line: the kernel silently ignores -# everything after the first newline, so an editor that appends one drops every -# argument that follows it. -CUR="$(tr -d '\n' < "$CMDLINE")" - -# Never leave a stale flag behind, and never leave two root= arguments — the -# kernel takes the last one, which would make a re-run's behaviour depend on -# argument order. -CUR="$(printf '%s\n' "$CUR" \ - | sed -e 's| *root=[^ ]*||g' \ - -e 's| *mb_encrypt=[^ ]*||g' \ - -e 's| *mb_rootdev=[^ ]*||g' \ - -e 's| *mb_otp_dryrun=[^ ]*||g' \ - -e 's| *| |g' \ - -e 's|^ *||' -e 's| *$||')" - -CUR="root=${MAPPER} ${CUR} mb_encrypt=1 mb_rootdev=PARTUUID=${ROOT_PARTUUID}" -[ "$DRY_RUN_OTP" = "1" ] && CUR="${CUR} mb_otp_dryrun=1" - -# consoleblank=0 — the kernel blanks the framebuffer console after ten minutes. -# cage owns the display so this is mostly invisible, until cage crashes and the -# board shows a black screen instead of the console that would explain why. -case " $CUR " in - *" consoleblank="*) ;; - *) CUR="${CUR} consoleblank=0" ;; -esac - -printf '%s\n' "$CUR" > "$CMDLINE" -echo " ${CMDLINE}:" -sed 's/^/ /' "$CMDLINE" - -# fstab: the root entry has to follow root= to the mapper. Matched on the mount -# point rather than on the device string, because what is in field 1 today -# depends on how this card was flashed. -awk -v mapper="$MAPPER" -v OFS='\t' ' - /^[[:space:]]*#/ { print; next } - $2 == "/" { $1 = mapper; print; next } - { print } -' /etc/fstab > /etc/fstab.mb-new -mv /etc/fstab.mb-new /etc/fstab - -grep -qE "^${MAPPER}[[:space:]]" /etc/fstab \ - || die "fstab rewrite did not take — restore /etc/fstab.mb-orig and investigate" -echo " /etc/fstab:" -grep -vE '^[[:space:]]*#' /etc/fstab | grep -vE '^[[:space:]]*$' | sed 's/^/ /' - -sync - -cat <&2; } -die() { echo "[otp-key] FATAL: $*" >&2; exit 1; } - -# ── Dry-run ────────────────────────────────────────────────────────────────── -# There is no undo for an OTP burn and no test lab for one. With -# MB_OTP_DRY_RUN=1 the "OTP" is a file, so the entire encrypt-and-boot cycle -# can be rehearsed on a loopback image on a build host. See -# scripts/luks-rehearsal.sh. -otp_read() { - if [ "${MB_OTP_DRY_RUN:-0}" = "1" ]; then - [ -f "$MB_OTP_DRY_RUN_FILE" ] || return 1 - cat "$MB_OTP_DRY_RUN_FILE" - return 0 - fi - "$OTP_TOOL" -l "$OTP_ROWS" -} - -otp_is_set() { - if [ "${MB_OTP_DRY_RUN:-0}" = "1" ]; then - [ -s "$MB_OTP_DRY_RUN_FILE" ] || return 1 - # Same "all zeros means unset" rule the real tool applies. - [ -n "$(tr -d '0' < "$MB_OTP_DRY_RUN_FILE" | tr -d '\n')" ] - return $? - fi - "$OTP_TOOL" -c -l "$OTP_ROWS" -} - -otp_write() { - key="$1" - if [ "${MB_OTP_DRY_RUN:-0}" = "1" ]; then - mkdir -p "$(dirname "$MB_OTP_DRY_RUN_FILE")" - printf '%s' "$key" > "$MB_OTP_DRY_RUN_FILE" - log "DRY RUN — wrote key to ${MB_OTP_DRY_RUN_FILE} instead of OTP" - return 0 - fi - # -y is not optional. Without it the tool prompts for confirmation when - # stdin is a terminal, and in an initramfs stdin IS the console: the board - # would sit forever at a "Type YES to continue" prompt that nobody is - # standing in front of. - # - # The tool performs its own readback comparison after writing and fails if - # it does not match, so there is no need to repeat that here. - "$OTP_TOOL" -y -l "$OTP_ROWS" -w "$key" -} - -MB_OTP_DRY_RUN_FILE="${MB_OTP_DRY_RUN_FILE:-/etc/musallahboard/otp-dry-run.key}" - -generate_key() { - # 32 bytes of kernel randomness as 64 lowercase hex characters. od is - # available as a busybox applet and is copied into the initramfs - # explicitly by the hook, so this works identically in both environments. - od -An -N32 -tx1 /dev/urandom | tr -d ' \n' -} - -derive() { - otp_hex="$1" - # Guard against deriving a passphrase from a blank or truncated read. An - # all-zero OTP read that silently produced a valid-looking passphrase would - # give every unprogrammed board in the fleet the same disk key. - case "$otp_hex" in - "") die "empty OTP read" ;; - esac - [ "${#otp_hex}" -eq $(( OTP_ROWS * 8 )) ] \ - || die "OTP read is ${#otp_hex} hex chars, expected $(( OTP_ROWS * 8 ))" - [ -n "$(printf '%s' "$otp_hex" | tr -d '0')" ] \ - || die "OTP is all zeros — refusing to derive a fleet-wide key" - - # No trailing newline. cryptsetup treats a --key-file argument - # asymmetrically: for `-` (stdin) it reads up to a newline, but for a - # regular file it uses the ENTIRE contents, newline included. So - # `musallahboard-otp-key > /run/key; cryptsetup --key-file /run/key` and - # `musallahboard-otp-key | cryptsetup --key-file -` would derive two - # different passphrases from the same OTP — and the second form is exactly - # what anyone debugging this by hand will type. Emitting no newline makes - # every path agree. - printf '%s:%s' "$DOMAIN" "$otp_hex" | sha256sum | cut -d' ' -f1 | tr -d '\n' -} - -# ── Entry points ───────────────────────────────────────────────────────────── -case "${1:---print}" in - --status) - if otp_is_set; then - echo "programmed" - else - echo "blank" - exit 1 - fi - ;; - - --ensure) - # THIS IS THE IRREVERSIBLE STEP. OTP bits go from 0 to 1 and never - # back. Called exactly once per board, from the initramfs, immediately - # before the root filesystem is encrypted. - if ! otp_is_set; then - log "OTP is blank — generating and burning a device key (PERMANENT)" - newkey="$(generate_key)" - [ "${#newkey}" -eq $(( OTP_ROWS * 8 )) ] \ - || die "generated key is the wrong length — refusing to burn" - otp_write "$newkey" - log "OTP programmed" - fi - derive "$(otp_read)" - ;; - - --print|"") - otp_is_set || die "OTP is blank — run with --ensure to program it" - derive "$(otp_read)" - ;; - - *) - die "unknown argument: $1" - ;; -esac diff --git a/packaging/musallahboard-agent-update.service b/packaging/musallahboard-agent-update.service index 6b6d78e..cd07e40 100644 --- a/packaging/musallahboard-agent-update.service +++ b/packaging/musallahboard-agent-update.service @@ -26,14 +26,13 @@ TimeoutStartSec=15min # Hardening. It needs to write /usr/bin (the binary), /usr/lib/musallahboard # (agent.prev, the journal, update-strikes.json), /var/lib/musallahboard -# (state.json, agent/last-update.json, agent/staged/ready) and -# /usr/share/musallahboard (the kiosk pages `splash install` refreshes after -# an update). It only reads /etc/musallahboard. Its only network use is the +# (state.json, agent/last-update.json, agent/staged/ready). It only reads +# /etc/musallahboard. Its only network use is the # loopback status check, and it talks to PID 1 over its private socket to # restart the agent and read its state, which a read-only /run does not # prevent. ProtectSystem=strict -ReadWritePaths=/usr/bin -/usr/lib/musallahboard /var/lib/musallahboard -/usr/share/musallahboard +ReadWritePaths=/usr/bin -/usr/lib/musallahboard /var/lib/musallahboard IPAddressDeny=any IPAddressAllow=localhost ProtectHome=yes diff --git a/packaging/musallahboard-agent.service b/packaging/musallahboard-agent.service index 0defec3..48a0b6f 100644 --- a/packaging/musallahboard-agent.service +++ b/packaging/musallahboard-agent.service @@ -55,8 +55,8 @@ PrivateTmp=yes # systemd creates and chowns these to User= on every start, so the installer # does not have to. /etc/musallahboard is NOT listed here on purpose: these -# directories appear only when the service first starts, and `enroll` has to -# be able to write agent.toml/agent.key before that has ever happened. The +# directories appear only when the service first starts, and `enroll` or +# `service-port` may write agent.toml before that has ever happened. The # installer creates the config dir itself for that reason. StateDirectory=musallahboard StateDirectoryMode=0750 @@ -65,8 +65,9 @@ LogsDirectoryMode=0750 # Redundant with the two directives above (systemd makes those writable even # under ProtectSystem=strict) but kept explicit for /etc/musallahboard, which -# is not managed by a *Directory= directive. The daemon writes kiosk-url there -# (write .tmp, rename), so the directory has to stay writable. +# is not managed by a *Directory= directive. The daemon writes agent.toml there +# when it applies a setup file or completes a claim, and agent.key when it +# claims (write .tmp, rename), so the directory has to stay writable. # # Writable here means "not read-only mounted", nothing more: ordinary # permissions still apply. trust.json in the same directory is root:root 0644, diff --git a/packaging/musallahboard-kiosk-reload.service b/packaging/musallahboard-kiosk-reload.service deleted file mode 100644 index a1f022f..0000000 --- a/packaging/musallahboard-kiosk-reload.service +++ /dev/null @@ -1,16 +0,0 @@ -[Unit] -Description=Reload the MusallahBoard kiosk after the composed URL changed -Documentation=https://github.com/LensBridge/agent -# Activated only by musallahboard-kiosk-watch.path. Restarting the kiosk makes -# start-kiosk.sh re-read /etc/musallahboard/kiosk-url, so the splash is -# replaced by the board (or vice-versa if the URL was cleared). -# -# No restart loop: restarting the kiosk does not touch kiosk-url, so it cannot -# re-trigger the .path watcher. The agent only writes kiosk-url when the -# composed value actually changed (it skips identical rewrites), so an -# already-enrolled device does not flicker on every boot. -After=musallahboard-kiosk.service - -[Service] -Type=oneshot -ExecStart=/bin/systemctl --no-block try-restart musallahboard-kiosk.service diff --git a/packaging/musallahboard-kiosk-watch.path b/packaging/musallahboard-kiosk-watch.path deleted file mode 100644 index aed9ea4..0000000 --- a/packaging/musallahboard-kiosk-watch.path +++ /dev/null @@ -1,17 +0,0 @@ -[Unit] -Description=Watch the composed kiosk URL and reload the kiosk on change -Documentation=https://github.com/LensBridge/agent -# The agent writes /etc/musallahboard/kiosk-url (atomically: write .tmp then -# rename into place) on enrollment and whenever the base board-url changes. -# systemd watches the parent directory's inotify, so the rename-into-place is -# caught even when the file did not previously exist (first enrollment). - -[Path] -# PathModified (not PathChanged): also fires on a plain write/rename without a -# preceding open of an existing file — which is exactly the agent's -# write-tmp + rename pattern on first enrollment. -PathModified=/etc/musallahboard/kiosk-url -Unit=musallahboard-kiosk-reload.service - -[Install] -WantedBy=multi-user.target diff --git a/packaging/musallahboard-kiosk.service b/packaging/musallahboard-kiosk.service index a7221ba..ca9dde7 100644 --- a/packaging/musallahboard-kiosk.service +++ b/packaging/musallahboard-kiosk.service @@ -1,13 +1,8 @@ [Unit] Description=MusallahBoard kiosk (cage + Chromium) Documentation=https://github.com/LensBridge/agent -# The kiosk launches IMMEDIATELY and shows the local "waiting for enrollment" -# splash (start-kiosk.sh falls back to waiting.html when /etc/musallahboard/ -# kiosk-url is absent/empty). There is deliberately NO ExecStartPre gate any -# more — gating before ExecStart left tty1 black until enrollment. Instead, -# musallahboard-kiosk-watch.path watches kiosk-url and restarts this unit the -# moment the agent writes it on enrollment, so the board replaces the splash -# within ~2s with no operator action. +# The kiosk always shows the agent's local server (start-kiosk.sh), on every +# board, provisioned or not. After=systemd-user-sessions.service # The kiosk loads http://127.0.0.1:8080/, served by the agent, and the agent # reports READY=1 (Type=notify) only once that server is listening. So ordering @@ -44,8 +39,6 @@ UtmpMode=user # Leading '-' = don't fail if the file is missing. EnvironmentFile=-/etc/musallahboard/kiosk.env -# No enrollment gate: start-kiosk.sh shows waiting.html until kiosk-url exists, -# then the .path watcher cycles us onto the real board. ExecStart=/usr/bin/start-kiosk.sh # cage exits when the browser dies; always bring the board back. ExecStopPost diff --git a/packaging/musallahboard-usb-import@.service b/packaging/musallahboard-usb-import@.service index d224202..6ddbcbd 100644 --- a/packaging/musallahboard-usb-import@.service +++ b/packaging/musallahboard-usb-import@.service @@ -4,7 +4,7 @@ Documentation=https://github.com/LensBridge/agent/blob/main/docs/architecture.md # Started by udev (/etc/udev/rules.d/90-musallahboard-usb.rules) for a USB # block device that carries a filesystem; %I is its kernel name, e.g. sda1. # The helper re-checks the name and the filesystem type, mounts it read-only -# with nosuid,nodev,noexec at /run/musallahboard/usb/%I, copies at most 16 +# with nosuid,nodev,noexec at /run/musallahboard/usb/%I, copies at most 64 # *.mbu regular files into the inbox, unmounts, and then waits for the # daemon's results so they land in this unit's journal # (docs/architecture.md section 9.6). `usb_import = false` in agent.toml makes @@ -17,8 +17,8 @@ Documentation=https://github.com/LensBridge/agent/blob/main/docs/architecture.md [Service] Type=oneshot ExecStart=/usr/bin/musallahboard-agent usb-import %I -# Copying up to 16 x 512 MiB from a slow stick, then up to 15 min waiting for -# the daemon. +# Copying up to 4 GiB from a slow stick, then up to 15 min waiting for the +# daemon. TimeoutStartSec=20min # The mount point. systemd creates it before start and removes it after. diff --git a/packaging/rtc/85-musallahboard-rtc.rules b/packaging/rtc/85-musallahboard-rtc.rules new file mode 100644 index 0000000..967c14b --- /dev/null +++ b/packaging/rtc/85-musallahboard-rtc.rules @@ -0,0 +1,8 @@ +# MusallahBoard: set the system clock from the RTC when it appears +# (installed by `musallahboard-agent install-system --rtc`, which +# `setup.sh --service-port --rtc` runs). The ds3231 driver is a module, so the +# kernel's own boot-time read of the RTC is over by the time it loads, and +# udev cannot set the clock itself (systemd-udevd runs without CAP_SYS_TIME), +# so it starts a oneshot unit that does. Writing the RTC back is the agent's +# job (90-musallahboard-rtc.rules gives it access). +ACTION=="add", SUBSYSTEM=="rtc", KERNEL=="rtc0", TAG+="systemd", ENV{SYSTEMD_WANTS}+="musallahboard-rtc.service" diff --git a/packaging/rtc/musallahboard-rtc.service b/packaging/rtc/musallahboard-rtc.service new file mode 100644 index 0000000..0a39ddc --- /dev/null +++ b/packaging/rtc/musallahboard-rtc.service @@ -0,0 +1,11 @@ +[Unit] +Description=Set the system clock from the RTC (MusallahBoard) +Documentation=https://github.com/LensBridge/agent +# Started by 85-musallahboard-rtc.rules when rtc0 appears. +DefaultDependencies=no +Before=time-set.target +Wants=time-set.target + +[Service] +Type=oneshot +ExecStart=/usr/sbin/hwclock --rtc=/dev/rtc0 --hctosys --utc diff --git a/packaging/start-kiosk.sh b/packaging/start-kiosk.sh index a8803d3..8ea6464 100644 --- a/packaging/start-kiosk.sh +++ b/packaging/start-kiosk.sh @@ -8,10 +8,11 @@ # at which point systemd (Restart=always) bounces us. This replaces the old # lightdm + labwc autologin stack: one systemd unit == the whole display. # -# The agent writes the URL to KIOSK_URL_FILE once the device is enrolled: -# its own local server, http://127.0.0.1:8080/. Until then the file is -# absent and we show the local "waiting for enrollment" splash; the kiosk -# .path watcher restarts us when the agent writes it. +# The kiosk always shows the agent's local server, http://127.0.0.1:8080/, +# provisioned or not (an unprovisioned board serves its "not set up yet" +# screen there). It opens it through the local starting.html, which waits for +# the agent to answer: loading the agent's URL while it is down would leave +# Chromium on its own "refused to connect" page. # # Browser: we must NOT use a snap. Snap Chromium runs in its own snapd cgroup # scope, so it survives `systemctl restart` @@ -21,22 +22,12 @@ # leftover /usr/bin/chromium-browser snap stub. set -euo pipefail -KIOSK_URL_FILE="/etc/musallahboard/kiosk-url" -SPLASH="file:///usr/share/musallahboard/waiting.html" +BOARD="http://127.0.0.1:8080/" +STARTING="/usr/share/musallahboard/starting.html" -STARTING="file:///usr/share/musallahboard/starting.html" - -URL="" -if [[ -r "$KIOSK_URL_FILE" ]]; then - URL="$(tr -d '[:space:]' < "$KIOSK_URL_FILE")" -fi -if [[ -z "$URL" ]]; then - URL="$SPLASH" -elif [[ -r "${STARTING#file://}" ]]; then - # Open the board through the local "starting" page, which waits for the - # agent to answer: loading the agent's URL while it is down would leave - # Chromium on its own "refused to connect" page. - URL="${STARTING}#${URL}" +URL="$BOARD" +if [[ -r "$STARTING" ]]; then + URL="file://${STARTING}#${BOARD}" fi # Resolve a real (non-snap) browser. A snap shim is a tiny shell script that @@ -97,6 +88,7 @@ exec cage -d -- "$BROWSER" \ --overscroll-history-navigation=0 \ --check-for-update-interval=31536000 \ --enable-features=OverlayScrollbar \ + --password-store=basic \ --user-data-dir="$PROFILE_DIR" \ --remote-debugging-port=9222 \ --remote-debugging-address=127.0.0.1 \ diff --git a/packaging/uninstall.sh b/packaging/uninstall.sh deleted file mode 100644 index 4835e54..0000000 --- a/packaging/uninstall.sh +++ /dev/null @@ -1,146 +0,0 @@ -#!/bin/bash -# ===================================================== -# MusallahBoard Agent Uninstall Script -# ===================================================== -# Stops and removes musallahboard-agent from a host. -# -# Usage: -# sudo bash uninstall.sh # keep device identity (config + key) -# sudo bash uninstall.sh --purge # also delete /etc/musallahboard -# # (irreversible — the Ed25519 key is gone) -# -# What is removed in the default mode: -# - /lib/systemd/system/musallahboard-*.{service,path} (stopped, disabled), -# including the self-updater and the USB import template -# - /etc/udev/rules.d/90-musallahboard-{usb,rtc}.rules -# - /etc/sudoers.d/musallahboard-agent -# - /usr/bin/musallahboard-agent, /usr/lib/musallahboard (rollback binary) -# - /var/lib/musallahboard (content, app, inbox, state) -# - /var/log/musallahboard -# - the service port, if set up: the musallahboard-service-port and -# musallahboard-lan NetworkManager connections, its ufw rules, and the -# RTC boot-time clock unit -# -# What is preserved (unless --purge): -# - /etc/musallahboard/agent.toml (device id, backend url) -# - /etc/musallahboard/agent.key (Ed25519 private key) -# - /etc/musallahboard/trust.json (pinned signing keys) -# - The service user account ('musallahdaemon') -# -# Re-installing later (without --purge) keeps the device's existing enrollment. -# ===================================================== - -set -euo pipefail - -RED='\033[0;31m'; YELLOW='\033[1;33m'; GREEN='\033[0;32m'; BOLD='\033[1m'; NC='\033[0m' -info() { echo -e "${GREEN}[INFO]${NC} $*"; } -warn() { echo -e "${YELLOW}[WARN]${NC} $*"; } -error() { echo -e "${RED}[ERROR]${NC} $*"; exit 1; } -section() { echo; echo -e "${BOLD}═══ $* ═══${NC}"; } - -PURGE=no -while [[ $# -gt 0 ]]; do - case "$1" in - --purge) PURGE=yes; shift ;; - -h|--help) sed -n '2,31p' "$0"; exit 0 ;; - *) error "Unknown flag: $1" ;; - esac -done - -[[ $EUID -ne 0 ]] && error "Run as root: sudo bash $0" - -section "Stopping service" -if systemctl list-unit-files musallahboard-agent.service &>/dev/null; then - systemctl stop musallahboard-agent.service 2>/dev/null || true - systemctl disable musallahboard-agent.service 2>/dev/null || true - info "Service stopped and disabled" -else - warn "Service unit not installed — nothing to stop" -fi - -section "Removing files" - -if systemctl list-unit-files musallahboard-kiosk-watch.path &>/dev/null; then - systemctl disable --now musallahboard-kiosk-watch.path 2>/dev/null || true -fi -# The self-updater first: it must not fire while the files below disappear. -systemctl disable --now musallahboard-agent-update.path 2>/dev/null || true -systemctl stop musallahboard-agent-update.service 2>/dev/null || true -systemctl stop 'musallahboard-usb-import@*.service' 2>/dev/null || true -# udev before the units, so a stick plugged in now starts nothing. -rm -f /etc/udev/rules.d/90-musallahboard-usb.rules -rm -f /etc/udev/rules.d/90-musallahboard-rtc.rules -rm -f /etc/modules-load.d/musallahboard.conf -udevadm control --reload 2>/dev/null || true -rm -f /lib/systemd/system/musallahboard-agent.service -rm -f /lib/systemd/system/musallahboard-kiosk.service -rm -f /lib/systemd/system/musallahboard-kiosk-watch.path -rm -f /lib/systemd/system/musallahboard-kiosk-reload.service -rm -f /lib/systemd/system/musallahboard-agent-update.path -rm -f /lib/systemd/system/musallahboard-agent-update.service -rm -f '/lib/systemd/system/musallahboard-usb-import@.service' -# Pre-/lib layout — harmless if absent, and leaving one behind would shadow a -# reinstall's unit, since /etc/systemd/system takes precedence over /lib. -rm -f /etc/systemd/system/musallahboard-agent.service -rm -f /etc/systemd/system/musallahboard-kiosk.service -rm -f /etc/systemd/system/musallahboard-kiosk-watch.path -rm -f /etc/systemd/system/musallahboard-kiosk-reload.service -rm -f /etc/sudoers.d/musallahboard-agent -rm -f /usr/bin/musallahboard-agent -rm -f /usr/bin/.musallahboard-agent.new -rm -rf /usr/lib/musallahboard -rm -f /usr/bin/start-kiosk.sh -rm -rf /usr/share/musallahboard -info "Removed binary, units (agent, self-updater, USB import, kiosk watcher), udev rules, launcher, splash, sudoers" - -# State / logs: never preserved — they don't contain identity, just runtime crud. -# Includes installed content and app releases. -rm -rf /var/lib/musallahboard -rm -rf /var/log/musallahboard -info "Removed /var/lib/musallahboard and /var/log/musallahboard" - -# The service port (setup.sh --service-port). Left behind, the -# service-port connection would keep eth0 able to act as a DHCP server with no -# agent to switch it off. -section "Removing the service port" -if command -v nmcli &>/dev/null; then - for conn in musallahboard-service-port musallahboard-lan; do - if nmcli -g NAME connection show 2>/dev/null | grep -qxF "$conn"; then - if nmcli connection delete "$conn" >/dev/null; then - info "Deleted NetworkManager connection $conn" - else - warn "Could not delete NetworkManager connection $conn" - fi - fi - done -fi -if command -v ufw &>/dev/null; then - ufw delete allow in on eth0 to any port 67 proto udp >/dev/null 2>&1 || true - ufw delete allow in on eth0 to any port 53 >/dev/null 2>&1 || true - ufw delete allow in on eth0 from 10.77.0.0/24 to any port 80 proto tcp >/dev/null 2>&1 || true - info "Removed the service port's DHCP/DNS/upload firewall rules (if present)" -fi -if [[ -e /etc/udev/rules.d/85-musallahboard-rtc.rules || -e /lib/systemd/system/musallahboard-rtc.service ]]; then - rm -f /etc/udev/rules.d/85-musallahboard-rtc.rules - rm -f /lib/systemd/system/musallahboard-rtc.service - udevadm control --reload 2>/dev/null || true - # The dtoverlay line in config.txt stays (the RTC is still fitted, and - # harmless), and fake-hwclock is not reinstalled. - info "Removed the RTC boot-time clock unit" -fi -if [[ "$PURGE" == "yes" ]]; then - warn "--purge: deleting device identity at /etc/musallahboard" - warn " (the Ed25519 private key will be lost — re-enrollment required)" - rm -rf /etc/musallahboard - info "Removed /etc/musallahboard" -else - if [[ -d /etc/musallahboard ]]; then - info "Preserved /etc/musallahboard (device identity)" - info " Use 'uninstall.sh --purge' if you want it gone." - fi -fi - -systemctl daemon-reload - -echo -info "musallahboard-agent uninstalled" diff --git a/packaging/update.sh b/packaging/update.sh deleted file mode 100644 index 22ef4d5..0000000 --- a/packaging/update.sh +++ /dev/null @@ -1,90 +0,0 @@ -#!/bin/bash -# ===================================================== -# MusallahBoard Agent Update Script -# ===================================================== -# Replaces the agent binary in place and restarts the service. Preserves -# /etc/musallahboard (device identity and trust.json) and the systemd unit / -# sudoers config — use install.sh instead if you also need to update those. -# -# This is the manual, admin-over-SSH path. Boards normally update themselves -# from signed agent packages (.mbu) instead: online through the release -# channel, offline from a USB stick or an upload on the service port. Those go -# through the root self-updater, which verifies signatures and rolls back a -# release that does not come up. This script does neither: it trusts the -# binary you give it, and it does not touch the version high-water mark, so it -# can also downgrade. -# -# Usage: -# sudo bash update.sh # uses ./musallahboard-agent next to script -# sudo bash update.sh /path/to/bin # uses the binary at the given path -# -# Typical remote-update flow from a dev box: -# scp build/musallahboard-agent-arm64 \ -# packaging/update.sh \ -# admin@pi:/tmp/ -# ssh admin@pi 'sudo bash /tmp/update.sh /tmp/musallahboard-agent-arm64' -# ===================================================== - -set -euo pipefail - -RED='\033[0;31m'; YELLOW='\033[1;33m'; GREEN='\033[0;32m'; NC='\033[0m' -info() { echo -e "${GREEN}[INFO]${NC} $*"; } -warn() { echo -e "${YELLOW}[WARN]${NC} $*"; } -error() { echo -e "${RED}[ERROR]${NC} $*"; exit 1; } - -[[ $EUID -ne 0 ]] && error "Run as root: sudo bash $0" - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -BINARY_DEST=/usr/bin/musallahboard-agent -SERVICE=musallahboard-agent.service -LIB_DIR=/usr/lib/musallahboard -PREV_DEST=${LIB_DIR}/agent.prev - -BINARY_SRC="${1:-}" -if [[ -z "$BINARY_SRC" ]]; then - # Look for a sibling binary; prefer arch-suffixed - for cand in \ - "$SCRIPT_DIR/musallahboard-agent-$(uname -m)" \ - "$SCRIPT_DIR/musallahboard-agent-arm64" \ - "$SCRIPT_DIR/musallahboard-agent-amd64" \ - "$SCRIPT_DIR/musallahboard-agent" - do - if [[ -x "$cand" ]]; then BINARY_SRC="$cand"; break; fi - done -fi -[[ -z "$BINARY_SRC" ]] && error "No binary found. Pass one as the first argument." -[[ -x "$BINARY_SRC" ]] || error "Not executable: $BINARY_SRC" - -# Sanity: refuse to install a binary that segfaults on `version` -if ! "$BINARY_SRC" version >/dev/null 2>&1; then - error "Binary at $BINARY_SRC failed 'version' smoke test — refusing to install." -fi -NEW_VERSION="$("$BINARY_SRC" version 2>&1 || true)" -OLD_VERSION="" -[[ -x "$BINARY_DEST" ]] && OLD_VERSION="$($BINARY_DEST version 2>&1 || true)" - -info "Replacing $BINARY_DEST" -info " old: ${OLD_VERSION:-}" -info " new: $NEW_VERSION" - -# Keep the running binary where the self-updater keeps its rollback copy, so -# a bad manual update can be undone the same way: -# sudo install -m 0755 /usr/lib/musallahboard/agent.prev /usr/bin/musallahboard-agent -if [[ -x "$BINARY_DEST" ]]; then - install -d -o root -g root -m 0755 "$LIB_DIR" - install -o root -g root -m 0755 "$BINARY_DEST" "$PREV_DEST" - info "Saved the previous binary as $PREV_DEST" -fi - -# Atomic replace: install(1) handles temp file + rename. -install -o root -g root -m 0755 "$BINARY_SRC" "$BINARY_DEST" - -if systemctl list-unit-files "$SERVICE" &>/dev/null; then - info "Restarting $SERVICE" - systemctl restart "$SERVICE" - sleep 1 - systemctl --no-pager --lines=5 status "$SERVICE" || true -else - warn "$SERVICE not installed — binary replaced but no service to restart." - warn "Run install.sh to fully install." -fi diff --git a/packaging/waiting.html b/packaging/waiting.html deleted file mode 100644 index eb45e38..0000000 --- a/packaging/waiting.html +++ /dev/null @@ -1,106 +0,0 @@ - - - - -MusallahBoard - - - -
Waiting for device enrollment…
-
- This screen clears automatically once the agent is enrolled. - - - -
MusallahBoard
- - - - - diff --git a/setup.sh b/setup.sh index 0a9d49b..c06c002 100755 --- a/setup.sh +++ b/setup.sh @@ -2,8 +2,9 @@ # ===================================================== # MusallahBoard — Raspberry Pi One-Line Installer # ===================================================== -# Provisions a fresh Raspberry Pi OS (Debian/trixie, arm64) into a fully -# configured MusallahBoard kiosk, ready for enrollment. +# Provisions a fresh Raspberry Pi OS (Debian/trixie, arm64) into a +# MusallahBoard kiosk. It needs internet once, here; the board never does +# again. # # Usage: # curl -fsSL https://raw.githubusercontent.com/lensbridge/agent/main/setup.sh | bash @@ -11,21 +12,22 @@ # Or with pre-supplied answers (no prompts): # curl -fsSL ... | MB_HOSTNAME=lobby MB_ADMIN_USER=admin \ # MB_TIMEZONE=America/Toronto \ -# MB_ADMIN_SSH_KEY="ssh-ed25519 AAAA..." bash +# MB_ADMIN_SSH_KEY="ssh-ed25519 AAAA..." \ +# MB_CONTENT_KEY="" bash # -# After setup completes, enroll the device: -# sudo musallahboard-agent enroll --token= --backend= +# The content signing public key is LensBridge's: the board only accepts +# content and setup files signed by it. The console shows it (and the backend +# publishes it at /api/agent/signing-keys). # -# The kiosk shows a "waiting for enrollment" splash until then; once enrolled -# it shows the board served by the local agent, with no reboot. Every board -# renders from its own disk and syncs content whenever it has internet -# (docs/architecture.md). +# After setup the board shows "This board is not set up yet". Plug in the +# setup USB stick exported from the LensBridge console (Devices, the board, +# Setup file or USB kit): the board takes its identity and its content from +# it, and, if its setup file names a backend, connects when it has internet. # -# Boards without internet: once the board is set up and enrolled, and while -# it still has internet, run +# The ethernet service port, where a laptop or phone plugged in can upload +# signed update packages, is switched on with # bash setup.sh --service-port [--rtc] -# to provision the ethernet service port, where a laptop or phone plugged in -# can upload signed update packages. USB sticks work on every board. +# USB sticks work on every board. # # Re-running this script is safe. # ===================================================== @@ -69,7 +71,7 @@ NTP_SYNC_TIMEOUT_SEC="${NTP_SYNC_TIMEOUT_SEC:-90}" # Every prompt can be answered in advance via environment variable. When piped # (stdin is the script itself), prompts cannot work — defaults are used. # -# MB_HOSTNAME MB_ADMIN_USER MB_TIMEZONE MB_ADMIN_SSH_KEY +# MB_HOSTNAME MB_ADMIN_USER MB_TIMEZONE MB_ADMIN_SSH_KEY MB_CONTENT_KEY # MB_ASSUME_YES=1 take the default for anything unset, confirm nothing # MB_REBOOT=auto|never|ask MB_ASSUME_YES="${MB_ASSUME_YES:-0}" @@ -84,14 +86,10 @@ BINARY_DEST=/usr/bin/musallahboard-agent # Where this script is published (for the instructions it prints). SETUP_URL=https://raw.githubusercontent.com/lensbridge/agent/main/setup.sh CONFIG_DIR=/etc/musallahboard -UNIT_DIR=/lib/systemd/system -SUDOERS_DEST=/etc/sudoers.d/musallahboard-agent -KIOSK_SHARE_DIR=/usr/share/musallahboard STATE_DIR=/var/lib/musallahboard INBOX_DIR=/var/lib/musallahboard/inbox LIB_DIR=/usr/lib/musallahboard TRUST_PATH=/etc/musallahboard/trust.json -UDEV_DIR=/etc/udev/rules.d # The kiosk always loads the agent's local server (docs/architecture.md, 14). KIOSK_URL="http://127.0.0.1:8080/" @@ -117,11 +115,12 @@ Usage: bash setup.sh [options] --admin-user=NAME SSH/sudo account --timezone=TZ e.g. America/Toronto --admin-ssh-key=KEY authorized public key for the admin account + --content-key=B64 LensBridge's content signing public key (base64) --reboot=auto|never|ask --yes, -y answer every prompt with its default -h, --help -Service port (after a normal setup and enrollment, while still online): +Service port (after a normal setup, while still online): --service-port provision the ethernet service port, where a laptop or phone plugged in can upload update packages, and turn it on; skips the normal setup @@ -138,6 +137,7 @@ for arg in "$@"; do --admin-user=*) export MB_ADMIN_USER="${arg#*=}" ;; --timezone=*) export MB_TIMEZONE="${arg#*=}" ;; --admin-ssh-key=*) export MB_ADMIN_SSH_KEY="${arg#*=}" ;; + --content-key=*) export MB_CONTENT_KEY="${arg#*=}" ;; --reboot=*) export MB_REBOOT="${arg#*=}" ;; --yes|-y) export MB_ASSUME_YES=1 ;; --service-port) SERVICE_PORT=1 ;; @@ -191,6 +191,12 @@ _confirm() { [[ $_reply =~ ^[Yy]$ ]] } +# valid_content_key: base64 (standard alphabet) of exactly 32 bytes, the format +# `musallahboard-agent trust add` takes. The agent checks it again. +valid_content_key() { + [[ "$1" =~ ^[A-Za-z0-9+/]{43}=$ ]] && [[ "$(printf '%s' "$1" | base64 -d 2>/dev/null | wc -c)" -eq 32 ]] +} + # ── Pre-flight checks ───────────────────────────────────────────────────────── preflight() { [[ $EUID -eq 0 ]] && error "Do not run as root. Run as a user with sudo access." @@ -263,6 +269,20 @@ prompt_config() { [[ "$SSH_PUB_KEY" =~ ^(ssh-|ecdsa-|sk-) ]] || \ error "That does not look like an SSH public key (it should start with ssh-ed25519, ssh-rsa or ecdsa-)." + echo + CONTENT_KEY="${MB_CONTENT_KEY-}" + if [[ -n "$CONTENT_KEY" ]]; then + info "Content signing key supplied" + elif _interactive; then + echo "Paste LensBridge's content signing public key (base64, from the console):" + read -rp "> " CONTENT_KEY < /dev/tty + fi + CONTENT_KEY="$(tr -d '[:space:]' <<< "$CONTENT_KEY")" + [[ -n "$CONTENT_KEY" ]] || \ + error "The content signing public key is required: without it the board accepts no content or setup file. Set MB_CONTENT_KEY." + valid_content_key "$CONTENT_KEY" || \ + error "That is not a content signing public key: it must be the base64 of 32 bytes (44 characters ending in =)." + echo info "Summary" printf " %-18s %s\n" "Hostname:" "$HOSTNAME" @@ -270,6 +290,7 @@ prompt_config() { printf " %-18s %s\n" "Kiosk user:" "$KIOSK_USER (auto-login, browser only, no sudo/SSH/shell)" printf " %-18s %s\n" "Kiosk URL:" "$KIOSK_URL (served by the agent)" printf " %-18s %s\n" "Timezone:" "$TIMEZONE" + printf " %-18s %s\n" "Content key:" "$CONTENT_KEY" echo if ! _confirm "Continue? (y/n): "; then exit 0 @@ -286,15 +307,13 @@ install_packages() { # cage: single-app Wayland kiosk compositor # chromium: deb browser (not snap) - # rpi-connect: Raspberry Pi Connect for remote access local pkgs=(cage chromium ufw unattended-upgrades apt-listchanges curl) - # rpi-connect is only in the Raspberry Pi OS archive. - [[ "$IS_VM" == "1" ]] || pkgs+=(rpi-connect) sudo apt-get install -y "${pkgs[@]}" - # Purge services that add unnecessary network attack surface + # Purge services that add unnecessary network attack surface. Raspberry + # Pi Connect was installed by earlier versions of this script. info "Purging unnecessary network services..." - sudo apt-get purge -y rpcbind nfs-common 2>/dev/null || true + sudo apt-get purge -y rpcbind nfs-common rpi-connect rpi-connect-lite 2>/dev/null || true sudo apt-mark hold rpcbind nfs-common 2>/dev/null || true } @@ -537,7 +556,7 @@ setup_ufw() { # ── Pi-specific extras ──────────────────────────────────────────────────────── setup_pi_extras() { if [[ "$IS_VM" == "1" ]]; then - info "Virtual machine: no hardware watchdog or Raspberry Pi Connect" + info "Virtual machine: no hardware watchdog" return fi section "Hardware watchdog" @@ -548,13 +567,6 @@ RuntimeWatchdogSec=15 RebootWatchdogSec=2min EOF info "Watchdog: systemd pings /dev/watchdog0 every 15s; reboots if it misses" - - section "Raspberry Pi Connect" - sudo loginctl enable-linger "$ADMIN_USER" - sudo systemctl stop wayvnc.service 2>/dev/null || true - sudo systemctl mask wayvnc.service 2>/dev/null || true - info "Linger enabled for $ADMIN_USER; system wayvnc.service masked" - warn "Post-install: ssh in as $ADMIN_USER and run 'rpi-connect signin'" } # ── Download and install agent binary ───────────────────────────────────────── @@ -573,251 +585,17 @@ install_agent_binary() { info "Installed $BINARY_DEST ($("$BINARY_DEST" version 2>/dev/null || echo 'version unknown'))" } -# ── Install sudoers allow-list ──────────────────────────────────────────────── -install_sudoers() { - section "Sudoers" - - sudo tee "$SUDOERS_DEST" > /dev/null << 'EOF' -# musallahboard-agent — privileged commands allow-list -musallahdaemon ALL=(root) NOPASSWD: /bin/systemctl restart musallahboard-kiosk.service -musallahdaemon ALL=(root) NOPASSWD: /bin/systemctl reboot -EOF - sudo chmod 0440 "$SUDOERS_DEST" - sudo chown root:root "$SUDOERS_DEST" - - # Validate syntax - if ! sudo visudo -c -f "$SUDOERS_DEST"; then - sudo rm -f "$SUDOERS_DEST" - error "Sudoers file failed validation" - fi - info "Installed $SUDOERS_DEST" -} - -# ── Install systemd units ───────────────────────────────────────────────────── -install_systemd_units() { - section "Systemd units" - - # KEEP IN SYNC with packaging/*.service, *.path and packaging/udev/. This - # script is curl|bash'd and has no checkout to copy from, so the units are - # inlined here without their comments; the packaged files explain them. - - # Agent service. CAP_SYS_TIME sets the clock (and, with the RTC rule, the - # RTC); CAP_NET_BIND_SERVICE is for the upload server on port 80. - sudo tee "$UNIT_DIR/musallahboard-agent.service" > /dev/null << 'EOF' -[Unit] -Description=MusallahBoard device agent -Documentation=https://github.com/LensBridge/agent -After=network-online.target -Wants=network-online.target -StartLimitIntervalSec=0 - -[Service] -Type=notify -User=musallahdaemon -Group=musallahdaemon -ExecStart=/usr/bin/musallahboard-agent run -Restart=always -RestartSec=5 -RestartSteps=6 -RestartMaxDelaySec=120 -WatchdogSec=60s -AmbientCapabilities=CAP_SYS_TIME CAP_NET_BIND_SERVICE -ProtectSystem=strict -ProtectHome=yes -PrivateTmp=yes -StateDirectory=musallahboard -StateDirectoryMode=0750 -LogsDirectory=musallahboard -LogsDirectoryMode=0750 -ReadWritePaths=/etc/musallahboard /var/lib/musallahboard /var/log/musallahboard -ProtectKernelTunables=yes -ProtectKernelModules=yes -ProtectControlGroups=yes -RestrictSUIDSGID=yes -LockPersonality=yes -RestrictRealtime=yes - -[Install] -WantedBy=multi-user.target -EOF - - # Kiosk service - sudo tee "$UNIT_DIR/musallahboard-kiosk.service" > /dev/null << 'EOF' -[Unit] -Description=MusallahBoard kiosk (cage + Chromium) -Documentation=https://github.com/LensBridge/agent -After=systemd-user-sessions.service -After=musallahboard-agent.service -Wants=musallahboard-agent.service -After=getty@tty1.service -Conflicts=getty@tty1.service - -[Service] -Type=simple -User=musallahkiosk -PAMName=login -TTYPath=/dev/tty1 -TTYReset=yes -TTYVHangup=yes -TTYVTDisallocate=yes -StandardInput=tty-fail -StandardOutput=journal -StandardError=journal -UtmpIdentifier=tty1 -UtmpMode=user -EnvironmentFile=-/etc/musallahboard/kiosk.env -ExecStart=/usr/bin/start-kiosk.sh -ExecStopPost=-/usr/bin/pkill -9 -u musallahkiosk -f "google-chrome|chromium" -Restart=always -RestartSec=2 - -[Install] -WantedBy=multi-user.target -EOF - - # Kiosk URL watcher (path unit) - sudo tee "$UNIT_DIR/musallahboard-kiosk-watch.path" > /dev/null << 'EOF' -[Unit] -Description=Watch the composed kiosk URL and reload the kiosk on change -Documentation=https://github.com/LensBridge/agent - -[Path] -PathModified=/etc/musallahboard/kiosk-url -Unit=musallahboard-kiosk-reload.service - -[Install] -WantedBy=multi-user.target -EOF - - # Kiosk reload service - sudo tee "$UNIT_DIR/musallahboard-kiosk-reload.service" > /dev/null << 'EOF' -[Unit] -Description=Reload the MusallahBoard kiosk after the composed URL changed -Documentation=https://github.com/LensBridge/agent -After=musallahboard-kiosk.service - -[Service] -Type=oneshot -ExecStart=/bin/systemctl --no-block try-restart musallahboard-kiosk.service -EOF - - # Root self-updater: the daemon stages a verified agent package and - # creates staged/ready; this re-verifies it as root, swaps the binary, - # keeps the new agent on probation and rolls back if it fails. The update - # journal in $LIB_DIR also starts it, to finish an interrupted update. - sudo tee "$UNIT_DIR/musallahboard-agent-update.path" > /dev/null << 'EOF' -[Unit] -Description=Watch for a staged MusallahBoard agent update -Documentation=https://github.com/LensBridge/agent/blob/main/docs/architecture.md - -[Path] -PathExists=/var/lib/musallahboard/agent/staged/ready -PathExists=/usr/lib/musallahboard/update-in-progress.json -Unit=musallahboard-agent-update.service - -[Install] -WantedBy=multi-user.target -EOF - - sudo tee "$UNIT_DIR/musallahboard-agent-update.service" > /dev/null << 'EOF' -[Unit] -Description=Apply a staged MusallahBoard agent update -Documentation=https://github.com/LensBridge/agent/blob/main/docs/architecture.md -After=musallahboard-agent.service - -[Service] -Type=oneshot -ExecStart=/usr/bin/musallahboard-agent selfupdate apply -TimeoutStartSec=15min -ProtectSystem=strict -ReadWritePaths=/usr/bin -/usr/lib/musallahboard /var/lib/musallahboard -/usr/share/musallahboard -IPAddressDeny=any -IPAddressAllow=localhost -ProtectHome=yes -PrivateTmp=yes -NoNewPrivileges=yes -ProtectKernelTunables=yes -ProtectKernelModules=yes -ProtectKernelLogs=yes -ProtectControlGroups=yes -ProtectHostname=yes -RestrictSUIDSGID=yes -RestrictRealtime=yes -RestrictNamespaces=yes -LockPersonality=yes -RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK -UMask=0022 -EOF - - # USB import helper, started by udev for each USB filesystem. Root (it - # mounts), no network, read-only system except the inbox. - sudo tee "$UNIT_DIR/musallahboard-usb-import@.service" > /dev/null << 'EOF' -[Unit] -Description=Import MusallahBoard packages from USB stick %I -Documentation=https://github.com/LensBridge/agent/blob/main/docs/architecture.md - -[Service] -Type=oneshot -ExecStart=/usr/bin/musallahboard-agent usb-import %I -TimeoutStartSec=20min -RuntimeDirectory=musallahboard/usb/%I -RuntimeDirectoryMode=0700 -PrivateNetwork=yes -ProtectSystem=strict -ReadWritePaths=/var/lib/musallahboard/inbox -ProtectHome=yes -PrivateTmp=yes -NoNewPrivileges=yes -ProtectKernelTunables=yes -ProtectKernelModules=yes -ProtectKernelLogs=yes -ProtectControlGroups=yes -ProtectClock=yes -ProtectHostname=yes -RestrictSUIDSGID=yes -RestrictRealtime=yes -RestrictNamespaces=yes -LockPersonality=yes -RestrictAddressFamilies=AF_UNIX -CapabilityBoundingSet=CAP_SYS_ADMIN CAP_DAC_OVERRIDE CAP_DAC_READ_SEARCH CAP_CHOWN CAP_FOWNER -UMask=0022 -EOF - - info "Installed systemd units" -} - -# ── Install udev rules ──────────────────────────────────────────────────────── -install_udev_rules() { - section "udev rules" - - # KEEP IN SYNC with packaging/udev/. - sudo mkdir -p "$UDEV_DIR" - sudo tee "$UDEV_DIR/90-musallahboard-usb.rules" > /dev/null << 'EOF' -# MusallahBoard: import signed update packages (*.mbu) from a USB stick. -ACTION=="add", SUBSYSTEM=="block", KERNEL=="sd[a-z]*", ENV{ID_BUS}=="usb", ENV{ID_FS_USAGE}=="filesystem", ENV{ID_FS_TYPE}=="vfat|exfat|ext4|ntfs|ntfs3", TAG+="systemd", ENV{SYSTEMD_WANTS}+="musallahboard-usb-import@%k.service" -EOF - sudo tee "$UDEV_DIR/90-musallahboard-rtc.rules" > /dev/null << 'EOF' -# MusallahBoard: let the agent (group musallahdaemon) write the RTC with hwclock. -SUBSYSTEM=="rtc", KERNEL=="rtc0", GROUP="musallahdaemon", MODE="0660" -EOF - sudo chmod 0644 "$UDEV_DIR/90-musallahboard-usb.rules" "$UDEV_DIR/90-musallahboard-rtc.rules" - - sudo udevadm control --reload || true - # Apply the rtc0 permissions now. Not the block subsystem: that would - # start an import from a stick that happens to be plugged in. - sudo udevadm trigger --subsystem-match=rtc --action=change || true - - # KEEP IN SYNC with packaging/modules-load.d/. The USB helper's sandbox - # (ProtectKernelModules=yes) cannot load filesystem drivers, so exFAT and - # NTFS sticks need them loaded at boot, and now. - sudo mkdir -p /etc/modules-load.d - printf '%s\n' \ - "# MusallahBoard: filesystem drivers for USB update sticks (see setup.sh)." \ - exfat ntfs3 | sudo tee /etc/modules-load.d/musallahboard.conf > /dev/null - sudo chmod 0644 /etc/modules-load.d/musallahboard.conf - sudo modprobe exfat 2>/dev/null || warn "Could not load exfat now; exFAT sticks work after a reboot" - sudo modprobe ntfs3 2>/dev/null || warn "Could not load ntfs3 now; NTFS sticks work after a reboot" - info "USB sticks start musallahboard-usb-import@.service; rtc0 is writable by $SERVICE_USER" +# ── System files ────────────────────────────────────────────────────────────── +# The systemd units, udev rules, sudoers allow-list, modules-load list, kiosk +# launcher and the kiosk's local page are embedded in the agent binary +# (packaging/ in the repository), so this script has no copies of them to +# keep in sync. install-system writes them, removes files earlier versions +# installed, reloads systemd and udev, and enables the units. +install_system_files() { + section "System files" + sudo "$BINARY_DEST" install-system + sudo systemctl start musallahboard-agent-update.path + info "Units, udev rules, sudoers and kiosk launcher installed from the agent binary" } # ── State directories and trust store ───────────────────────────────────────── @@ -835,7 +613,8 @@ install_state_dirs() { info "$INBOX_DIR ($SERVICE_USER 0770), $LIB_DIR (root 0755)" # Root-owned, world-readable, never overwritten: it holds the content keys - # pinned at enrollment and any release keys an admin added. + # pinned here, by `trust fetch` or at enrollment, and any release keys an + # admin added. if sudo test -e "$TRUST_PATH"; then info "Keeping existing $TRUST_PATH" else @@ -847,108 +626,12 @@ install_state_dirs() { fi } -# ── Install kiosk launcher script ───────────────────────────────────────────── -install_kiosk_launcher() { - section "Kiosk launcher" - - sudo tee /usr/bin/start-kiosk.sh > /dev/null << 'LAUNCHER' -#!/bin/bash -set -euo pipefail - -KIOSK_URL_FILE="/etc/musallahboard/kiosk-url" -SPLASH="file:///usr/share/musallahboard/waiting.html" -STARTING="file:///usr/share/musallahboard/starting.html" - -URL="" -if [[ -r "$KIOSK_URL_FILE" ]]; then - URL="$(tr -d '[:space:]' < "$KIOSK_URL_FILE")" -fi -if [[ -z "$URL" ]]; then - URL="$SPLASH" -elif [[ -r "${STARTING#file://}" ]]; then - # Through the local "starting" page, which waits for the agent to answer - # instead of leaving Chromium on its "refused to connect" page. - URL="${STARTING}#${URL}" -fi - -pick_browser() { - local cand - for cand in google-chrome-stable google-chrome chromium chromium-browser; do - local path - path="$(command -v "$cand" 2>/dev/null)" || continue - case "$(readlink -f "$path")" in - /snap/*) continue ;; - esac - if head -c4 "$path" | grep -q $'\x7fELF' || file -b "$path" 2>/dev/null | grep -qi 'ELF'; then - echo "$path"; return 0 - fi - if ! grep -qi 'snap' "$path" 2>/dev/null; then - echo "$path"; return 0 - fi - done - return 1 -} - -BROWSER="$(pick_browser)" || { - echo "start-kiosk: no non-snap browser found" >&2 - exit 1 -} - -PROFILE_DIR="${HOME:-/home/$(id -un)}/.musallahboard-kiosk" -mkdir -p "$PROFILE_DIR" - -exec cage -d -- "$BROWSER" \ - --ozone-platform=wayland \ - --disable-dev-shm-usage \ - --kiosk \ - --noerrdialogs \ - --disable-infobars \ - --disable-session-crashed-bubble \ - --disable-restore-session-state \ - --no-first-run \ - --start-fullscreen \ - --disable-translate \ - --disable-features=TranslateUI \ - --disable-pinch \ - --overscroll-history-navigation=0 \ - --check-for-update-interval=31536000 \ - --enable-features=OverlayScrollbar \ - --password-store=basic \ - --user-data-dir="$PROFILE_DIR" \ - --remote-debugging-port=9222 \ - --remote-debugging-address=127.0.0.1 \ - "$URL" -LAUNCHER - - sudo chmod 0755 /usr/bin/start-kiosk.sh - info "Installed /usr/bin/start-kiosk.sh" -} - -# ── Install splash page ─────────────────────────────────────────────────────── -install_splash_page() { - section "Splash page" - # The page is embedded in the agent binary (packaging/waiting.html), so a - # curl|bash setup gets the same bytes as a packaged install, and a - # self-update refreshes it. The binary is installed before this runs. - sudo "$BINARY_DEST" splash install "$KIOSK_SHARE_DIR/waiting.html" - info "Installed $KIOSK_SHARE_DIR/waiting.html" -} - -# ── Enable services ─────────────────────────────────────────────────────────── -enable_services() { - section "Enable services" - - sudo systemctl daemon-reload - sudo systemctl enable musallahboard-agent.service - sudo systemctl enable musallahboard-kiosk.service - sudo systemctl enable musallahboard-kiosk-watch.path - sudo systemctl enable musallahboard-agent-update.path - - # Start the watchers now: one catches enrollment, the other a staged update - sudo systemctl start musallahboard-kiosk-watch.path - sudo systemctl start musallahboard-agent-update.path - - info "Services enabled" +# ── Content signing key ─────────────────────────────────────────────────────── +# Pinned through the agent's own root-only trust path, which checks the key +# and the file again and leaves an already trusted key alone. +pin_content_key() { + section "Content signing key" + sudo "$BINARY_DEST" trust add content "$CONTENT_KEY" "lensbridge (setup.sh)" } # ── Apply appliance policy ──────────────────────────────────────────────────── @@ -977,25 +660,25 @@ print_summary() { cat << EOF +----------------------------------------------------------+ - | Setup complete - device READY FOR ENROLLMENT | + | Setup complete | +----------------------------------------------------------+ Hostname : $HOSTNAME Admin SSH : ssh $ADMIN_USER@ Kiosk URL : $KIOSK_URL (served by the agent) - FINAL STEP - enroll this device (once, with a token from the admin UI): + FINAL STEP - plug in this board's setup USB stick, exported from the + LensBridge console (Devices, the board, Setup file or USB kit). The board + takes its identity, content, board app and agent from it; it needs no + internet. Until then the screen says "This board is not set up yet" and + shows the board's address (the to SSH to). - sudo musallahboard-agent enroll \\ - --token= --backend= + If its setup file names a backend, the board connects to LensBridge by + itself whenever it has internet. (Maintainers can still enroll with a + token: sudo musallahboard-agent enroll --token= --backend=) - Until then the kiosk shows the local "waiting" splash, which prints this - device's IP address on screen once it has one - that is the to SSH to. - On enrollment the kiosk switches to the board served by the agent, which - starts syncing content and downloads the board app within a few minutes. - - A board that will not have internet: after enrolling, turn on the ethernet - service port (laptop and phone updates at http://10.77.0.1/): + Laptop and phone updates over the ethernet service port + (http://10.77.0.1/): sudo musallahboard-agent service-port on To fit a DS3231 clock module as well, re-run this setup with --rtc: curl -fsSL $SETUP_URL | bash -s -- --service-port --rtc @@ -1029,7 +712,7 @@ EOF # ══ Service port (setup.sh --service-port) ════════════════════════════════════ # Everything below runs only with --service-port, on a board that has already -# been set up and enrolled. See docs/architecture.md, sections 9.5 and 13. +# been set up. See docs/architecture.md, sections 9.5 and 13. # Every step is idempotent: re-running it is safe, and is how you add --rtc # later. @@ -1042,9 +725,6 @@ service_port_preflight() { error "nmcli not found. The service port needs NetworkManager (the Raspberry Pi OS default)." [[ -x "$BINARY_DEST" ]] || \ error "$BINARY_DEST is not installed. Run the normal setup (without --service-port) first." - sudo test -s "$CONFIG_DIR/agent.toml" || \ - error "This board is not enrolled yet. Enroll it online first: - sudo musallahboard-agent enroll --token= --backend=" } service_port_install_packages() { @@ -1175,29 +855,10 @@ service_port_rtc() { info "fake-hwclock not installed" fi - # The ds3231 driver is a module, so the kernel's own boot-time read of the - # RTC is over by the time it loads, and udev cannot set the clock itself - # (systemd-udevd runs without CAP_SYS_TIME). Instead udev starts a oneshot - # unit when rtc0 appears, and that unit reads the RTC. Writing it back is - # the agent's job (90-musallahboard-rtc.rules gives it access). - sudo tee /etc/udev/rules.d/85-musallahboard-rtc.rules > /dev/null << 'EOF' -# MusallahBoard: set the system clock from the RTC when it appears. -ACTION=="add", SUBSYSTEM=="rtc", KERNEL=="rtc0", TAG+="systemd", ENV{SYSTEMD_WANTS}+="musallahboard-rtc.service" -EOF - sudo tee "$UNIT_DIR/musallahboard-rtc.service" > /dev/null << 'EOF' -[Unit] -Description=Set the system clock from the RTC (MusallahBoard) -Documentation=https://github.com/LensBridge/agent -DefaultDependencies=no -Before=time-set.target -Wants=time-set.target - -[Service] -Type=oneshot -ExecStart=/usr/sbin/hwclock --rtc=/dev/rtc0 --hctosys --utc -EOF - sudo systemctl daemon-reload - sudo udevadm control --reload + # musallahboard-rtc.service reads the RTC when udev sees rtc0 (the + # ds3231 driver is a module, so the kernel's own boot-time read is over by + # then). Writing it back is the agent's job. + sudo "$BINARY_DEST" install-system --rtc info "RTC read at boot via musallahboard-rtc.service" warn "Reboot once with the RTC fitted. The agent saves the time to it whenever it corrects the clock," warn "for example on the next upload from a laptop (mbpush or http://10.77.0.1/)." @@ -1291,13 +952,9 @@ main() { setup_pi_extras install_agent_binary - install_sudoers install_state_dirs - install_systemd_units - install_udev_rules - install_kiosk_launcher - install_splash_page - enable_services + pin_content_key + install_system_files apply_appliance_policy print_summary diff --git a/uninstall.sh b/uninstall.sh index aae1b2c..d662cb9 100644 --- a/uninstall.sh +++ b/uninstall.sh @@ -145,6 +145,7 @@ systemctl reload NetworkManager 2>/dev/null || true info "System configurations removed" # ── Unmask wayvnc ───────────────────────────────────────────────────────────── +# Boards set up before Raspberry Pi Connect was dropped have it masked. section "Restoring masked services" systemctl unmask wayvnc.service 2>/dev/null || true @@ -177,7 +178,7 @@ cat << 'EOF' - Watchdog, logind, WiFi power-save configs NOT removed (do manually if needed): - - Packages (cage, chromium, rpi-connect, ufw, etc.) + - Packages (cage, chromium, ufw, etc.) - Admin user and SSH key - Hostname and timezone - UFW rules other than the service port's diff --git a/update-anim/embed.go b/update-anim/embed.go index 88b0c06..22ceebe 100644 --- a/update-anim/embed.go +++ b/update-anim/embed.go @@ -1,7 +1,7 @@ // Package updateanim embeds the board's "Working on updates" screen // (index.html beside this file) so the agent can serve it with no other files // on disk. The page is driven over CDP through window.mbUpdate; see the -// comment at the bottom of index.html and internal/updatescreen. +// comment at the bottom of index.html and internal/core/kiosk/screen.go. package updateanim import _ "embed" diff --git a/vm/README.md b/vm/README.md index 045744b..551ed7f 100644 --- a/vm/README.md +++ b/vm/README.md @@ -25,27 +25,30 @@ architecture is emulated, which works but is very slow. ## Getting started ```sh -vm/mbvm create # first time: downloads Debian, runs setup.sh (a few minutes) -vm/mbvm enroll --token= --backend=http://localhost:8080 --insecure-dev +# first time: downloads Debian, runs setup.sh (a few minutes). The key is +# the backend's content signing public key (GET /api/agent/signing-keys). +MBVM_CONTENT_KEY= vm/mbvm create +# set it up like a Pi: plug in a "USB stick" with its setup file and content +vm/mbvm usb setup-xxxxxxxx.mbu content-xxxxxxxx.mbu ``` -`localhost` in `--backend` means your computer: mbvm rewrites it to the -address the VM reaches your computer at (10.0.2.2). A deployed backend URL is -passed through unchanged. +The board takes its identity from the setup file, installs the content, and +fetches the board app from its release channel when it has internet. A setup +file exported for an online board also makes it claim its key and connect. -The agent only enrolls over `https://` (with a `wss://` socket on the same -host). A local backend on plain http needs `--insecure-dev`, which the VM's -config keeps as `insecure_dev = true`; the backend must then hand out a -`ws://` URL on the host the board used, `10.0.2.2`, which it does when it -builds the URL from the request's `Host`. For a deployed backend leave the -flag off: +A maintainer can enroll it with a token instead: ```sh -vm/mbvm enroll --token= --backend=https://backend.example.org +vm/mbvm enroll --token= --backend=http://localhost:8080 --insecure-dev ``` -Once enrolled, the board installs the latest board app from its release -channel, syncs content and shows the board, exactly like a Pi. +`localhost` in `--backend` means your computer: mbvm rewrites it to the +address the VM reaches your computer at (10.0.2.2). A deployed backend URL is +passed through unchanged. The agent only talks to an `https://` backend (with +a `wss://` socket on the same host). A local backend on plain http needs +`--insecure-dev`, which the VM's config keeps as `insecure_dev = true`, and +the backend's `musallahboard.agent.websocketUrl` must then be a `ws://` URL +on `10.0.2.2`. ## Commands @@ -53,7 +56,7 @@ channel, syncs content and shows the board, exactly like a Pi. |---|---| | `create [--agent=V]` | Provision a new VM and start it | | `start [--headless]` / `stop` | Boot or shut down; the board keeps its state | -| `reset [--agent=V]` | Back to a freshly provisioned, unenrolled board | +| `reset [--agent=V]` | Back to a freshly installed board that is not set up yet | | `agent V` | Install agent `V` on the running board, keeping its state | | `enroll --token=T --backend=URL` | Enroll the board | | `usb FILE.mbu...` / `usb --remove` | Plug in, or pull out, a USB stick holding these files | @@ -131,6 +134,7 @@ All are environment variables: | `MBVM_MEMORY`, `MBVM_CPUS` | `2048`, `2` | | | `MBVM_RESOLUTION` | `1920x1080` | The board is designed for 1080p. The window scales to fit | | `MBVM_TIMEZONE` | `America/Toronto` | Passed to `setup.sh` | +| `MBVM_CONTENT_KEY` | (required for `create`/`rebuild`) | The backend's content signing public key, which `setup.sh` pins | | `MBVM_DISPLAY` | cocoa or gtk | A raw QEMU `-display` value, such as `vnc=127.0.0.1:1` | | `MBVM_QEMU_ARGS` | | Extra QEMU arguments | | `MBVM_IMAGE_URL` | Debian 13 generic cloud image | | @@ -150,7 +154,7 @@ All are environment variables: board can go back to an older version, which a real board, updated only through signed packages, never does. - **VM detection.** `setup.sh` notices it is in a VM. It then accepts amd64 - as well as arm64, and skips the Pi-only steps (Raspberry Pi Connect and the - hardware watchdog). The kiosk uses software rendering. + as well as arm64, and skips the Pi-only step (the hardware watchdog). + The kiosk uses software rendering. - **What a VM cannot do.** There is no ethernet service port, no RTC, and no real display hardware. Test those on a Pi. diff --git a/vm/mbvm b/vm/mbvm index 9c0207b..1491eb7 100755 --- a/vm/mbvm +++ b/vm/mbvm @@ -35,6 +35,8 @@ CPUS="${MBVM_CPUS:-2}" DISK_SIZE="${MBVM_DISK_SIZE:-16G}" RESOLUTION="${MBVM_RESOLUTION:-1920x1080}" TIMEZONE="${MBVM_TIMEZONE:-America/Toronto}" +# LensBridge's content signing public key, which setup.sh pins. +CONTENT_KEY="${MBVM_CONTENT_KEY:-}" # Host ports for `tunnel`: the board's local server and Chromium's DevTools. TUNNEL_BOARD_PORT="${MBVM_BOARD_PORT:-18080}" TUNNEL_CDP_PORT="${MBVM_CDP_PORT:-19222}" @@ -81,7 +83,7 @@ checkout), or the path to an agent binary. Settings (environment): MBVM_NAME (several VMs side by side; give each its own MBVM_SSH_PORT), MBVM_ARCH (amd64|arm64, default: this computer's), -MBVM_MEMORY, MBVM_CPUS, MBVM_RESOLUTION, MBVM_TIMEZONE, MBVM_DISPLAY (a raw +MBVM_MEMORY, MBVM_CPUS, MBVM_RESOLUTION, MBVM_TIMEZONE, MBVM_CONTENT_KEY, MBVM_DISPLAY (a raw QEMU -display value), MBVM_QEMU_ARGS (extra QEMU arguments), MBVM_HOME. EOF } @@ -357,8 +359,8 @@ install_agent() { sudo systemctl stop musallahboard-agent sudo install -o root -g root -m 0755 /tmp/musallahboard-agent.new /usr/bin/musallahboard-agent rm -f /tmp/musallahboard-agent.new - # Agents before 0.3.0 have no embedded splash; keep the installed one. - sudo musallahboard-agent splash install /usr/share/musallahboard/waiting.html >/dev/null 2>&1 || true + # Its system files: agents before install-system keep what is there. + sudo musallahboard-agent install-system >/dev/null 2>&1 || true sudo systemctl start musallahboard-agent' local got got="$(vm_ssh musallahboard-agent version 2>/dev/null | head -1 || true)" @@ -441,11 +443,12 @@ provision() { wait_for_ssh "$limit" vm_ssh 'cloud-init status --wait >/dev/null 2>&1 || true' + [[ -n "$CONTENT_KEY" ]] || die "set MBVM_CONTENT_KEY to the backend's content signing public key (base64; GET /api/agent/signing-keys)" info "Running setup.sh from $REPO_DIR" vm_scp "$REPO_DIR/setup.sh" /tmp/setup.sh if ! vm_ssh "MB_ASSUME_YES=1 MB_REBOOT=never MB_HOSTNAME=musallahboard-vm \ MB_ADMIN_USER=$ADMIN_USER MB_TIMEZONE='$TIMEZONE' \ - MB_ADMIN_SSH_KEY='$(cat "$KEY.pub")' bash /tmp/setup.sh"; then + MB_ADMIN_SSH_KEY='$(cat "$KEY.pub")' MB_CONTENT_KEY='$CONTENT_KEY' bash /tmp/setup.sh"; then vm_ssh 'sudo poweroff' >/dev/null 2>&1 || true wait_for_exit 60 || kill "$(cat "$PIDFILE")" 2>/dev/null || true die "setup.sh failed (its output is above). The VM was not saved; fix it and run: vm/mbvm rebuild"