BifrOSt

public

Latest change 37dc9d785aa6ca46b85dceaa167406dd7efb3237 - Refresh documentation for the released 0.2.2 by Ólafur Búi Ólafsson

# BifrOSt Operating System Agent Guide

## Scope

This repository builds and releases the BifrOSt operating system. It owns the ArchISO profile, installer, installed-system payload, maintenance and update utilities, trust roots, signed ALPM and Flatpak catalog tooling, release evidence, and publication paths.

First-party sandboxed application development belongs in [`../BifrOSt-Apps`](../BifrOSt-Apps) locally and [`olibuijr/BifrOSt-Apps`](https://github.com/olibuijr/BifrOSt-Apps) on GitHub. That repository owns app source, Flatpak manifests, metadata, translations, tests, and unsigned candidate bundles. Do not add independent end-user app source or manifests here.

Keep the installer, Update Assistant, maintenance utility, welcome utility, privileged helpers, OS configuration, embedded public keys, admission policy, and catalog publication code in this repository. Changes to the app namespace, branch, catalog URL, trust key, signing process, or publication contract require coordinated changes and verification in both repositories.

## Safety invariants

- Treat installer target selection, source validation, destructive confirmation, partitioning, encryption, bootloader installation, and pre-wipe revalidation as load-bearing safety code.
- Never weaken target identity checks, live-media ancestry checks, mounted/active-device checks, minimum-size checks, source readiness, or the final exact-path confirmation.
- BifrOSt supports complete Arch Linux upgrades through `pacman -Syu`; do not introduce partial-upgrade paths.
- Do not claim Secure Boot, offline completeness, reproducibility, rollback, or hardware qualification beyond recorded evidence.
- Private release keys never belong in Git, command-line arguments, logs, or repository fixtures. Tracked public keys and exact fingerprints are trust inputs; update every embedded and published copy together. Signing keys were rotated on 2026-08-07; the current fingerprints live in `STATUS.md` and the tracked `keys/` files.
- Preserve the separation between the narrowly scoped BifrOSt ALPM repository and official Arch repositories.

## Application catalog contract

The Update Assistant discovers signed applications dynamically. It accepts only `org.bifrost.*` applications from the pinned HTTPS repository and embedded application-release key. Do not add a hard-coded application registry.

At the current `main` revision, the production catalog contains no application refs. An empty Update Assistant is therefore correct until a real candidate from BifrOSt-Apps is reviewed, signed, and published. `org.bifrost.TemplateCheck` is an ephemeral template-validation identity denylisted by the dispatcher, not a product or catalog candidate. Update this status text when the first real application is published; do not encode the temporary empty state in updater logic.

Application development and local validation produce unsigned reviewed `.flatpak` candidates and per-bundle candidate manifests in BifrOSt-Apps. Final release operators use `dispatch-app-release.py` here to:

1. admit each bundle only against its reviewed candidate manifest (matching bundle SHA-256, source repository and revision, app ID, branch, and architecture);
2. stage immutable copies and report SHA-256 digests;
3. reject refs outside the trusted namespace;
4. import into a staging OSTree repository;
5. sign commits and repository metadata with the protected key;
6. publish the catalog consumed by installed BifrOSt systems.

Never move the signing key or direct catalog publication into BifrOSt-Apps. Both repositories are CI-free; all validation, signing, and publication run locally under operator control.

## Verification

Run the narrowest check that exercises the changed contract, followed by repository validation when release inputs changed:

```bash
python3 -m unittest discover -s tests -v
python3 validate-build.py
```

Both repositories carry no GitHub Actions workflows, and `validate-build.py` rejects a `.github` directory. QEMU release-candidate qualification runs locally per `docs/qemu-test-plan.md` and produces ISO-digest-bound evidence with per-case install durations; `publish-release.py` consumes that evidence directly and stages assets immutably. A verified installer seed (`prepare-installer-cache.py --require`) is mandatory before an ISO build.

For application catalog changes, exercise an actual candidate through a local, non-production repository before publication, then verify list, install, launch, update, and rollback in a BifrOSt VM.

For installer or installed-system behavioral changes, build the ISO and follow `docs/qemu-test-plan.md`. Build success alone is not installation verification. UI changes require launching the affected interface and exercising the changed path.

Release metadata is generated evidence. Do not hand-edit digests, provenance fields, signatures, or qualification results to make validation pass.

## Repository hygiene

Generated ISO, VM, work, release, cache, and signing material must remain untracked. Treat unexpected working-tree changes as user work and do not overwrite them. Reuse the existing installed-root and packaging patterns rather than introducing a second source for the same shipped file.