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, controlled filesystem operations, and bounded Generic Netlink runtime reads |
| 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` 5.19.0          | Async 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.
- `wireguard-uapi` remains an approved option but is not selected for the bounded runtime reader: its public read API does not expose a receive deadline or a complete-dump guarantee. A systemd D-Bus request being accepted is not proof of job completion or successful VPN application.
- Runtime observation uses the already approved `rustix` 1.1.5 safe `net` and `event` APIs for a nonblocking Linux Generic Netlink socket, polling and datagram I/O. This keeps one monotonic deadline and exact truncation/sender checks around the checked WireGuard decoder. It does not add a direct dependency or use a subprocess.
- The systemd adapter pins `zbus` 5.19.0 with default features disabled and `async-io` plus `p2p` enabled. It first uses the system bus, then selects `/run/systemd/private` peer mode only when the bus connection reports a missing/refused/disconnected endpoint, before submitting any restart request. Permission errors, authentication/protocol failures, and deadline expiry do not trigger fallback. Private mode uses EXTERNAL authentication and checks the peer UID is root. Bus calls use the systemd well-known destination; private calls omit the destination and avoid bus-daemon owner monitoring. zbus's local peer signal matching tracks `JobRemoved` after systemd `Subscribe`. Each call uses zbus's asynchronous APIs driven by a small standard-library wake/park loop so operations share the caller's monotonic deadline. zbus's async-io backend owns internal I/O executor thread(s); callers must allow the connection to be dropped after each operation. Signal polling uses zbus 5.19.0's doc-hidden `export::futures_core` re-export to avoid another direct dependency; keep zbus pinned until that implementation is deliberately migrated. The private systemd socket is an internal systemd interface and may change between releases.
- 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](../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 and the existing configured systemd service. Restart uses the system D-Bus when available and can use systemd's root-only `/run/systemd/private` peer socket when the bus endpoint is unavailable. Permission or authentication failures and timeouts stop the operation without trying the private socket. The private socket is not a stable public systemd API. 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.