wireguard-admin/docs/DEPENDENCIES.md

Dependency Policy and Approved Choices

Read this document before changing dependencies, features, or build/runtime requirements. The approved choices may be introduced without renewed approval; unapproved direct dependencies require prior user agreement.

Approved dependencies

The user has approved the following choices. They may be introduced when their implementation stage needs them without requesting approval again. Approval does not mean they are already installed. Select compatible maintained versions and minimal features, and record exact resolved versions in Cargo.lock.

Purpose	Approved crates	Intended use
Terminal UI	ratatui, crossterm	Widgets, layout, keyboard events, terminal lifecycle
Serialization and settings	serde, toml	Typed application settings and metadata; TOML backup manifests
Typed errors	thiserror	Recoverable domain and adapter errors
Address ranges	ipnet	IPv4/IPv6 subnet validation and allocation support
Dates	time	UTC metadata, backup timestamps, handshake display
QR encoding	qrcode	Additional terminal delivery of client configurations
Backup archives	tar	Archives with manifests; initially without compression
Temporary files	tempfile	Staged file replacement and isolated test directories
Linux operations	rustix	User checks and controlled low-level filesystem operations
Encrypted vault	age	Recipient encryption and password protection of the vault secret key
WireGuard key pairs	x25519-dalek	Key generation and public/private key matching
Secure randomness	getrandom	Operating-system randomness for key generation
WireGuard key encoding	base64	Reading and writing WireGuard key representations
Secret handling	secrecy, zeroize	Explicit secret exposure and supported memory cleanup
WireGuard runtime	wireguard-uapi	Direct Linux interface, peer, handshake, and traffic queries
Service management	zbus	Direct systemd D-Bus requests and job completion tracking
Container integration tests	testcontainers	Alpine server/client lifecycle; development dependency only

• Use a separate vault key pair from all WireGuard client/server key pairs. Encrypt each client secret to the vault public key; protect the vault secret key with password-based encryption using the established age format. Do not replace this with password-only encryption of every new client record, which would require a password on creation.
• Validate wireguard-uapi against the isolated integration environment before relying on it. A systemd D-Bus request being accepted is not proof of job completion or successful VPN application.
• Avoid incompatible duplicate versions of secret-handling types where library APIs exchange them. Use supported re-exports where appropriate rather than adding redundant direct dependencies.
• Additional direct dependencies still require the comparison and prior agreement required by AGENTS.md, including any test/build helpers. Transitive dependencies of approved crates are resolved through Cargo; review their compatibility and runtime requirements. Do not add a direct tokio dependency merely because an approved library uses an async runtime internally.
• clap, chrono, SQLite, a generic INI writer, a mocking framework, and archive compression libraries are not part of the approved initial set. Use the standard library for the small startup argument surface and background threads/channels where sufficient.

External runtime and build requirements

• Production requires Linux with WireGuard support, the existing configured systemd service, and the system D-Bus needed by zbus. Existing wg-quick service dependencies remain necessary if that is how the service manages the interface.
• The application uses library APIs rather than invoking wg, systemctl, age, qrencode, tar, or openssl for its own operations. Test fixture setup and the existing WireGuard service may use their required system tools; that does not create an application subprocess fallback.
• Rust/Cargo and the target toolchain/linker are build requirements, not production application requirements. Verify the release binary's actual dynamic-library requirements rather than promising an automatically static executable.
• A Docker-API-compatible runtime, test images, and container tools belong to the integration environment only. Production does not need Docker or Testcontainers.