karapace/CHANGELOG.md

Changelog

All notable changes to Karapace will be documented in this file.

The format is based on Keep a Changelog.

[Unreleased] — 2.0 Hardening

Breaking Changes

• Store format v2 — STORE_FORMAT_VERSION bumped to 2. New staging/ and wal/ directories. Version 1 stores require rebuild.
• CLI pruned to 23 commands — removed legacy commands: init, preset, list-presets, export-app, unexport-app, quick, validate, verify-lock, export, list-images, remove-image, remote-list, tui.
• Content-addressed layers — LayerStore::put() now returns the blake3 content hash used as filename. Callers must use the returned hash for references.
• Engine::gc() requires &StoreLock — compile-time enforcement that callers hold the store lock before garbage collection.
• MetadataStore checksum — EnvMetadata now includes an optional checksum field (blake3). Written on every put(), verified on every get(). Backward-compatible via serde(default).

Added — 2.0 Hardening (M1–M8)

• M1: WAL Crash Safety — Fixed race windows in build() and restore() (rollback registered before side-effects). Added WAL protection to destroy(), commit() (layer manifest rollback), and gc() (WAL marker). 8 new WAL crash-safety tests.
• M2: Integrity Hardening — LayerStore::get() verifies blake3 hash on every read. MetadataStore embeds and verifies blake3 checksum. verify_store_integrity() expanded to check objects, layers, and metadata. 4 new integrity tests.
• M3: GC Safety — Engine::gc() now requires &StoreLock parameter (type-enforced). Snapshot layers whose parent is a live base layer are preserved during GC.
• M4: Remote Protocol — X-Karapace-Protocol: 1 header sent on all HTTP backend requests (PUT, GET, HEAD). PROTOCOL_VERSION constant exported from karapace-remote. 4 new header/auth verification tests via header-capturing mock server.
• M5: unwrap() Audit — 0 unwrap() in production src/ code. 4 Mutex::lock().unwrap() calls in MockBackend replaced with proper RuntimeError propagation.
• M6: Failure Mode Testing — 11 new tests: WAL write failure on read-only dir, build failure when WAL dir is read-only (disk-full simulation), stop() SIGTERM with real process (ESRCH path), stop() with non-existent PID, permission denied on object read, read-only metadata dir, concurrent GC lock contention, layer corruption detection, metadata corruption detection, destroy nonexistent env, invalid manifest.
• M7: Coverage Expansion — verify_store_integrity() now checks objects + layers + metadata (was objects-only). IntegrityReport expanded with layers_checked/passed and metadata_checked/passed fields. New tests: freeze/archive state transitions, rename environment, verify-store after fresh build, rebuild preserves new and cleans old, HTTP list_blobs, large (1MB) blob roundtrip.
• Total: 417 tests (24 ignored, require privileged operations). Clippy -D warnings clean. cargo fmt clean. Release build OK.

Added — 1.0 Preparation

• Real tar layers — pack_layer()/unpack_layer() in karapace-store: deterministic tar creation (sorted entries, zero timestamps, owner 0:0) for regular files, directories, and symlinks. Content-addressed via blake3.
• Snapshot system — Engine::commit() captures overlay upper as a tar snapshot; Engine::restore() atomically unpacks a snapshot via staging directory swap; Engine::list_snapshots() lists snapshots for an environment.
• CLI: snapshots and restore — new commands for snapshot management.
• Write-ahead log (WAL) — store/wal/{op_id}.json tracks in-flight operations with rollback steps. Engine::new() auto-recovers on startup. Integrated into build(), commit(), restore().
• Newtype wrappers threaded through all structs — EnvId, ShortId, ObjectHash, LayerHash now used in EnvMetadata across all 8 crates. Transparent serde for backward compatibility.
• Engine::push/pull — transfer logic moved from karapace-remote to Engine methods. karapace-remote is now pure I/O.
• CoreError::Remote — new error variant for remote operation failures.
• CLI stability contract — docs/cli-stability.md defines stable command signatures for 1.x.
• Remote protocol spec — docs/protocol-v1.md (v1-draft) documents blob store routes, push/pull protocol, registry format.
• Layer limitations doc — docs/layer-limitations-v1.md documents Phase 1 limits (no xattrs, device nodes, hardlinks).

Changed

• CLI monolith decomposition — split main.rs into ~30 command modules under commands/, thin dispatcher in main.rs.
• Error type cleanup — added StoreError::InvalidName and StoreError::NameConflict variants; removed Io(Error::other) hacks.
• D-Bus serialization cleanup — replaced hand-rolled JSON with typed serde response structs.
• Engine store caching — MetadataStore, ObjectStore, and LayerStore cached as fields on Engine.
• Remote integrity verification — pull_env verifies blake3 hash of each downloaded object and layer.
• Store spec updated — docs/store-spec.md reflects v2 format with WAL, staging, tar_hash, name field.
• README updated — reflects 23 commands, snapshot workflow, remote push/pull examples.

[0.1.0] — 2026-02-20

Added

• Deterministic environment engine — content-addressed, hash-based environment identity from resolved lock files.
• Manifest v1 — declarative TOML manifest with strict schema validation, deterministic normalization, and canonical serialization.
• Lock file v2 — resolved packages with pinned versions, base image content digest (not tag), dual verification (integrity + manifest intent).
• Content-addressable store — blake3 hashing, atomic writes (NamedTempFile + persist), integrity verification on read, reference counting, garbage collection with signal cancellation.
• CLI commands — build, rebuild, enter, exec, destroy, stop, freeze, archive, list, inspect, diff, snapshots, commit, restore, gc, verify-store, push, pull, rename, completions, man-pages, doctor, migrate.
• Example manifests — examples/minimal.toml, examples/dev.toml, examples/gui-dev.toml, examples/ubuntu-dev.toml, examples/rust-dev.toml for common use cases.
• Multi-distro image support — openSUSE Tumbleweed/Leap, Ubuntu (20.04–24.10), Debian (Bookworm/Trixie/Sid), Fedora (40–42), Arch Linux, custom URLs.
• Runtime backends — user namespace (unshare + fuse-overlayfs + chroot), OCI (crun/runc/youki), mock (for testing).
• Host integration — Wayland, X11, PipeWire, PulseAudio, D-Bus session bus, GPU (/dev/dri), audio (/dev/snd), SSH agent, fonts, themes, cursor themes, GTK/icon themes.
• Desktop app export — export GUI applications from environments as .desktop files on the host.
• Overlay drift control — diff, freeze, commit, export writable layer changes.
• D-Bus desktop integration — socket-activated org.karapace.Manager1 service (feature-gated, opt-in).
• Security model — mount whitelist, device policy, environment variable allow/deny lists, resource limits, no privilege escalation.
• Structured logging — log + env_logger with KARAPACE_LOG env var and --verbose/-v CLI flag.
• Concurrency safety — StoreLock file locking on all mutating CLI and D-Bus operations, GC protects active/archived environments.
• Automated tests — unit tests, integration tests, crash injection tests, concurrent build safety, GC safety, reproducibility.
• Shell completions — karapace completions bash|zsh|fish|elvish|powershell for tab completion.
• Man page generation — karapace man-pages <dir> generates man pages for all commands.
• Prerequisite detection — early check for unshare, fuse-overlayfs, curl with distro-aware install instructions.
• CI pipeline — GitHub Actions workflow: format, clippy, test, release build with artifact upload.

Security

• Shell injection prevention via POSIX single-quote escaping (shell_quote) on all sandbox script interpolation.
• Environment variable key validation ([a-zA-Z0-9_] only).
• Image download integrity — blake3 digest stored on download, verify_image() detects corruption.
• Destroy guard — cannot destroy a running environment (must stop first).
• Atomic rebuild — new environment built before old one is destroyed (no data loss on failure).
• PID cast safety — i32::try_from() instead of as i32 for libc::kill().
• Zero unwrap() in production code — all error paths handled gracefully.
• Input validation in quick command — image and package names validated against TOML injection.
• Cargo.lock committed for reproducible builds.

Documentation

• Manifest v0.1 specification (docs/manifest-spec.md)
• Lock file v2 specification (docs/lock-spec.md)
• Store format specification (docs/store-spec.md)
• Hash contract (docs/hash-contract.md)
• Security model with threat model and attack surface (docs/security-model.md)
• Public API reference (docs/api-reference.md)
• Versioning policy (docs/versioning-policy.md)
• CONTRIBUTING.md — development workflow, architecture principles, code standards.
• LICENSE — European Union Public Licence v1.2 (EUPL-1.2).