Add integration tests based on VM

docs/OPERATIONS.md

@@ -0,0 +1,150 @@
+# Operator setup, backup and recovery
+
+This guide describes the supported single-interface installation and recovery
+boundaries. Use it only after qualifying the application for the target host;
+the current evidence and gaps are listed in
+[`RELEASE_READINESS.md`](RELEASE_READINESS.md). Do not trial the application on
+a production service as a substitute for the pending disposable systemd VM
+qualification.
+
+## Installation prerequisites and placement
+
+The application manages one already-configured Linux WireGuard interface and
+its existing systemd service. The host must provide working WireGuard kernel
+support, systemd and its system D-Bus, plus the required service setup (such as
+`wg-quick` when the selected unit uses it). Version 1 does not provision a
+server, install a service, or manage multiple interfaces. Do not mount the
+development host's D-Bus into a test environment.
+
+Build with the pinned Rust 1.97.1 toolchain and locked dependencies. Before
+installing an artifact, verify its target and dynamic library requirements
+against the chosen Linux distribution. The current x86-64 GNU release candidate
+is host-assessed only; it has not been started in a guest. Keep the executable
+and `wireguard-admin.toml` together in a dedicated root-owned directory that
+ordinary users cannot modify. Keep the executable outside `PATH`; no installer,
+service unit, or automatic privilege wrapper is supplied.
+
+Copy [`../config/wireguard-admin.example.toml`](../config/wireguard-admin.example.toml)
+to `wireguard-admin.toml` beside the executable and edit it for the existing
+interface, server configuration, client source directory, address pools,
+endpoint, DNS, systemd unit, and timeout. The server config path and interface
+name are installation invariants. Relative paths resolve beside the executable,
+not from the shell's working directory. By default working data is
+`Backup/data` and archives are `Backup/archives`, also beside the executable.
+Test the resolved paths before running management. Preserve the existing
+configuration and imported client files; import is read-only and anomaly
+reports require operator decisions.
+
+Restrict the settings file, server configuration, vault, internal state, and
+backup tree to root. Existing server configuration and vault files must already
+be mode `0600` or stricter when opened. Keep private directories at `0700` and
+secret-bearing files at `0600`; the application creates new owned outputs with
+these modes but does not silently chmod an unsafe existing server/vault file.
+Do not make the executable or settings writable by unprivileged users. The
+application requires root for management; `--help` and `--version` are
+unprivileged.
+
+## Initial vault, import and delivery
+
+At initial setup, import scans the configured source directory without changing
+or deleting its original files. Review every reported match, mismatch, invalid
+file, or server-only/client-only anomaly. The server peer set remains
+authoritative; do not treat an imported file as permission to rewrite server
+settings.
+
+Choose and protect the vault password during initial vault creation. The
+password protects the separate vault secret key; it does not encrypt the
+server configuration, original client files, or backup archives. Losing it
+prevents future reissue of stored client private keys. A backup restores the
+encrypted vault but cannot recover a lost password. Store credentials under
+your organization's separate secret-custody process; never place the password
+in settings, a command line, logs, or evidence.
+
+For a new client, Commit first, then complete first file delivery in the same
+application session. The initial file is mandatory and can be retried at a
+different destination after a publication failure while that creation session
+is still active. Optional QR output represents the same configuration and is
+available only after file publication. The delivered file is plaintext
+WireGuard configuration, mode `0600`; treat terminal QR output as a disclosure.
+If publication reports uncertain output or cleanup is required, follow the
+exact manual-cleanup instruction before retrying; do not assume an error means
+no plaintext file was created.
+Until the saved peer set has been explicitly applied and verified, treat the
+new client's access as inactive. After that session ends, each reissue requires
+the vault password for that client and reads installed saved state. The
+application does not use retained original plaintext files as a password-free
+fallback. Overwriting a selected output file requires confirmation.
+
+## Commit, backups, restore and restart
+
+Keep the three states distinct:
+
+1. **Draft** is the current session's proposed edit. Cancel preserves it in
+   that session; exiting does not save it.
+2. **Saved** is what Commit installed on disk. Commit creates a mandatory
+   pre-Commit backup, then saves settings, server configuration, internal state
+   and encrypted vault. Commit never reloads, syncs, or restarts WireGuard.
+3. **Applied** is saved state verified against the running interface after an
+   explicit restart. A historical verification marker after reopen is not a
+   live observation.
+
+Every Commit, restore and restart first creates a complete mandatory backup.
+If that backup fails, the protected operation stops before changing saved files
+or submitting a restart. Backups are uncompressed archives, not encrypted
+archives. They can contain the server's private configuration and encrypted
+vault records. Restrict them to root, include them in the site's protected
+backup custody, and remember that a backup beside the executable is lost with
+that disk. The application has no automatic retention or remote-copy feature.
+Deleting a client from the current vault does not erase old backups.
+
+Restore is a previewed, confirmed full replacement of saved state. It restores
+the settings and opaque vault without a vault password, and it does not change
+the running interface. A restored archive's old verification marker is
+historical; runtime state becomes unknown. To apply the restored state, start a
+separate explicit restart and inspect its result. Never describe restore or
+Commit as a VPN rollback.
+
+Before confirming restart, review the configured interface/service and the
+saved-versus-applied differences. The application creates a pre-restart backup,
+submits the configured systemd job, waits for its terminal result, compares the
+complete observed peer and route sets, then journals verification state. A
+successful systemd job alone does not establish that the expected peers are
+active. A pre-restart backup captures saved files and is not necessarily a
+known-good working VPN state. Deleted-client addresses remain reserved until
+verification and its saved-state write both succeed.
+
+If restart reports failure, timeout, a runtime mismatch, or a persistence
+failure, read the stage and whether submission occurred or may still complete.
+A timeout does not cancel a submitted job. Do not immediately issue repeated
+restarts while a submitted job may still be running. No automatic restart,
+retry, VPN rollback, or reservation release occurs on these failure paths.
+Preserve the pre-restart backup and inspect the service and configured
+interface through the host's normal, independently controlled administration
+path. Do not infer success from log text alone. When the application remains
+usable, select a known-good archive through its preview/confirmation flow to
+restore saved files, then decide separately whether to restart and verify them.
+
+## Saved-file journal recovery
+
+The persistence journal recovers interrupted file replacement; it is not
+runtime rollback. On reopen, an uncommitted prepared journal rolls saved files
+back to the recorded prior bytes, while a committed journal is cleaned up. If
+recovery or cleanup fails, the application returns `RecoveryRequired` and
+rejects mutations. Correct the underlying storage problem (for example,
+available space or directory access), preserve the journal, and retry opening
+the application so its recovery can run. Do not delete, hand-edit, or rename
+journal files to force startup.
+
+If a journal remains invalid or recovery continues to fail, stop making
+changes. Preserve the complete data directory and operation backups for a
+careful, separately reviewed recovery. A known-good archive is the documented
+saved-state recovery source when the application can safely preview and restore
+it; it does not repair the runtime automatically. After saved state is recovered,
+inspect the live interface and use a separate explicit restart only when its
+target is understood. If the application cannot open to perform a safe
+previewed restore, do not improvise by copying partial archive members over
+installation paths.
+
+Never remove old archives or original client files as an automatic response to
+an error. Keep secret-bearing files and working backups out of source control,
+support tickets, screenshots, logs, and evidence reports.