Add Codex specific files

2026-10-18 21:33:52 +03:00
parent 86dbead893
commit 7b475bfcc8
13 changed files with 652 additions and 0 deletions
@@ -0,0 +1,40 @@
+# 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](../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.