Add specification

.idea/.gitignore

@@ -0,0 +1,14 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Ignored default folder with query files
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml
+/misc.xml
+/modules.xml
+/wireguard-admin.iml
+/vcs.xml

CONTEXT.md

@@ -0,0 +1,27 @@
+# WireGuard Client Management
+
+Terminology for managing device access to a WireGuard VPN.
+
+## Language
+
+**Draft**:
+Changes prepared by the administrator but not yet saved through Commit.
+
+**Commit**:
+Saving prepared changes without applying them to the running VPN.
+
+**Unapplied changes**:
+Differences between the saved configuration and the running VPN state. Applied through a separate restart operation.
+
+**Backup**:
+A copy of the saved server configuration, client metadata, and encrypted vault. Drafts and existing unencrypted client files are excluded.
+
+**Client**:
+An individual device with its own key pair and VPN connection configuration. One person may have multiple clients.
+_Avoid_: User, account
+
+**Client alias**:
+An administrator-friendly name for a client. A client is identified by its public key rather than its alias.
+
+**Anomalous client record**:
+A record with only a server configuration entry or only a client connection file, without its corresponding counterpart. Records are matched by public key and are not automatically repaired when discovered.

docs/IMPLEMENTATION.md

@@ -0,0 +1,45 @@
+# Implementation Plan
+
+Basis: the approved [specification](SPEC.md). This document defines the order of work without changing the requirements. Specific libraries and serialization formats remain implementation decisions.
+
+## 1. Model and configuration
+
+Create the Rust project and types for clients, address ranges, managed metadata, drafts, and applied state. Resolve application settings relative to the executable. Require root when launching the management interface, while allowing module tests to run without root.
+
+Outcome: settings are loaded with required fields validated; data locations do not depend on the working directory.
+
+## 2. Preserving the server file
+
+Implement document parsing that preserves original fragments, editing restricted to `[Peer]` sections and managed comments, import, and anomaly detection. Define a versioned comment format. Do not replace the entire configuration using ordinary INI serialization, which may discard comments and unknown parameters.
+
+Validation: fixture configurations covering comments, IPv4/IPv6, unknown parameters, and existing clients; untouched portions must remain byte-for-byte identical.
+
+## 3. Keys and vault
+
+Choose a maintained cryptographic library with an established asymmetric encryption format. Use the operating system's random number generator, a password-protected secret key, and a versioned vault format. Do not develop custom cryptographic primitives. Keep temporarily decrypted secrets out of logs and the ordinary TUI model.
+
+Validation: encryption without a password, correct and incorrect passwords, corrupted records, key matching during import, and absence of plaintext client secrets in persisted application data.
+
+## 4. Backups, Commit, and restore
+
+Define a versioned archive with a manifest describing its contents, creation reason, and verified application status. Prevent recursive inclusion of archives and arbitrary writes from archive entries outside permitted destination paths.
+
+Organize file and vault persistence so that write failures cannot be reported as a successful Commit. This protects write integrity and is not a concurrent editing mechanism. Create the mandatory backup before modifying operations.
+
+Validation: a complete save/restore cycle in a temporary directory, no restart during Commit, operation cancellation on backup failure, and restoration without vault decryption.
+
+## 5. Running VPN adapter
+
+Choose a minimal mechanism for reading current peers, handshakes, and counters; consider a direct Linux API instead of invoking utilities. Restart the configured systemd service, wait with a timeout, then verify the interface and clients. Isolate system calls from application logic.
+
+Validation: a controllable test adapter for failures and state transitions, plus a separate integration environment for real WireGuard/systemd. Do not use the production VPN as a test environment.
+
+## 6. Connection delivery and TUI
+
+Choose maintained TUI and QR libraries. Build the list, creation and alias forms, deletion confirmation, change preview, Commit, restart, import, and backup list. Add masked password input, output path selection, and retrying initial delivery after a failure.
+
+Validation: user scenarios from creation through delivery, deletion through address release, restoration without a password, and exiting with a draft. Verify terminal restoration after errors and absence of secret display outside explicit delivery actions.
+
+## 7. Acceptance and operation
+
+Prepare example settings, instructions for running from a dedicated root-only directory, and documentation for import, password custody, backups, and manual recovery. Run formatting, static analysis, tests, and a build for the target host architecture. Record integration results and any limitations not verified on the server separately.

docs/SPEC.md

@@ -0,0 +1,117 @@
+# WireGuard Admin — Version 1 Specification
+
+Status: approved by the user on 2026-10-18. This document records the discussion outcome; no new requirements have been added.
+
+## Purpose
+
+A native Rust application with a terminal user interface (TUI), run as root directly on a Linux VPN server. It manages one existing WireGuard interface and supports existing clients. Initial VPN server setup is outside the scope of version 1.
+
+Rust build dependencies are allowed. System utilities may be invoked only when necessary. The server uses systemd; the service name and operation timeout are configurable. The executable resides in a dedicated root-only directory and is not installed in PATH.
+
+## Data locations
+
+- Application settings reside alongside the executable. Their location is resolved relative to the executable, not the current working directory.
+- The data location is configurable; its default is a `Backup` directory alongside the executable.
+- Within that directory, `data` contains current internal data and the encrypted vault, while `archives` contains backups.
+- The directory containing existing client files is specified in the settings.
+- VPN server paths are invariant for installation and restoration. Migration between servers with different paths is not supported.
+
+## Data sources
+
+The server configuration is the source of truth for clients and their descriptive metadata. Clients are matched by public key. A client is an individual device with its own key pair. An alias is a convenient label; duplicate aliases are allowed.
+
+The application may modify only client `[Peer]` sections and their associated managed comment blocks. The rest of the server configuration, including interface parameters, network setup commands, unknown parameters, and administrator comments, is preserved. These settings are changed manually by the administrator.
+
+A versioned comment block immediately preceding `[Peer]` contains the alias and creation date in UTC. An unknown creation date for an existing client is not fabricated. The public key resides in `[Peer]` and is not duplicated in metadata. Passwords and client private keys are never included in comments.
+
+Separate application metadata contains internal state only; an independent copy of aliases is not a source of truth.
+
+## New client parameters
+
+The application settings file contains the server endpoint, IPv4 and IPv6 allocation ranges, and DNS addresses. A new client receives one address from each range. The first available address is selected by default, but the administrator may select an address manually. A deleted client's address is not reused until a successful restart.
+
+All client traffic is routed through the VPN: `0.0.0.0/0` and `::/0`. Existing IPv4-only clients are preserved without adding IPv6. Additional user settings for MTU, PersistentKeepalive, and preshared key generation are not introduced in version 1; existing connection parameters are preserved.
+
+## Operations and states
+
+Supported operations are creation, deletion, viewing, and alias changes. IP changes and key replacement are not separate operations in version 1; deletion and creation are used instead.
+
+There are three states:
+
+1. Draft: prepared changes that have not been saved.
+2. Saved state: files after Commit; these may differ from the running VPN.
+3. Applied state: the running interface matches the saved clients.
+
+Commit saves changes to files and the vault. Commit does not invoke reload, syncconf, or restart and does not change the running VPN. The TUI separately shows draft changes and saved but unapplied changes. A client deleted from the files may retain access until changes are applied.
+
+Restart is a separate action using the configured systemd service. If a draft exists, the choices are “Discard draft and restart” and “Cancel.” Cancel preserves the draft in the current session. After systemd completes successfully, the application verifies that the expected interface exists and its clients match the saved configuration. Only after verification is the state marked applied and deleted clients' addresses released.
+
+On normal exit, the application warns that the draft will be discarded. Drafts do not persist across launches. Restoration also warns that the draft will be discarded.
+
+A single administrator is assumed. Optimistic locking, concurrent edit detection, and automatic merging are not required. Automatic rollback after a failed restart is not required: the error is displayed, and the administrator selects a backup to restore.
+
+## Encrypted vault
+
+An asymmetric scheme is used: the public key allows new client secrets to be encrypted without a password. The vault's secret key is protected by a password set during initial creation. The password is needed only to decrypt a client's private key when reissuing connection details and is requested separately for each client.
+
+Losing the password makes saved client private keys impossible to decrypt. Restoring a backup does not recover the password. A new key pair can be issued to a client through deletion and creation.
+
+The password does not protect the entire archive, the server private key, the server-side copy of an existing preshared key, or retained original files. Access to secret data is restricted to root.
+
+When a client is deleted, Commit removes its record and secrets from the current vault. Previously created backups are not rewritten and may still contain those secrets.
+
+## Connection delivery
+
+Initial delivery is allowed after a successful Commit without a password during the client's creation session. Delivery after exiting the application requires a password.
+
+Delivery must save a standard WireGuard connection file to the selected directory, without password encryption, accessible only to root. A terminal QR code is an additional option. An existing file is not overwritten without confirmation. Delivered files are not automatically deleted.
+
+If saving the file fails, the administrator may resolve the issue, change the directory, and retry initial delivery without a password during the same creation session. Once initial delivery is complete, subsequent delivery requires a password. Until the configuration is applied, a warning states that access has not yet been activated.
+
+## Importing existing clients
+
+During initial vault creation, existing client files from the configured directory are checked and encrypted at the earliest opportunity. Original files are neither modified nor deleted; the administrator handles any subsequent cleanup.
+
+Validation results and anomalies are shown explicitly:
+
+- a server entry exists without a client file;
+- only a client file exists;
+- both parts exist;
+- the public key matches, but parameters such as the IP address differ;
+- a file is invalid and cannot be imported.
+
+Invalid files are skipped with an explanation. Anomalies are not automatically repaired. Explicit import of an existing file and deletion of a server entry are available.
+
+The private key is checked against the public key before import. If parameters differ, the server configuration takes precedence; the secret may be imported after key verification, but reissuing is blocked until the administrator explicitly resolves the discrepancy.
+
+Adding standard metadata blocks to existing clients goes through draft and Commit. Administrator comments are preserved. Until a standard alias exists, the client filename or shortened public key is displayed temporarily.
+
+## Backups and restoration
+
+A backup includes application settings, the server configuration, internal metadata, and the complete encrypted vault. Drafts, original unencrypted client files, and previous archives are excluded. The server configuration may contain secrets, so archive access is restricted to root.
+
+Backups are created manually and automatically before every Commit, restoration, and restart. If a mandatory backup cannot be created, further steps of the current operation stop. Automatic archive cleanup is not provided.
+
+The TUI displays the backup list, creation date and reason, and identifies the last state whose restart was successfully verified. A pre-Commit backup contains the previous saved state, which may differ from the running VPN. A pre-restart backup is also not necessarily a working state.
+
+Restoration requires a preview and confirmation. A precautionary backup is created first. The saved state is fully replaced with the selected archive contents; clients are not merged. The encrypted vault is restored as a whole without a password. Settings are also restored. The running VPN remains unchanged until a separate restart.
+
+## Client screen and statistics
+
+The list displays the alias, shortened public key, IPv4/IPv6, change state, and anomalies. The last handshake and the current interface's received/transmitted byte counters are refreshed periodically.
+
+The time of the last handshake is shown instead of an ambiguous “online” label. Counters are current WireGuard values, without daily or monthly history. Service logs and application action history are outside the scope of version 1.
+
+## Acceptance criteria
+
+- Commit does not change the running interface or start the service.
+- Client changes do not alter any server parameter outside managed records and blocks.
+- Existing clients, keys, and original files are preserved during initial import.
+- Creation, deletion, aliases, and restoration correctly follow draft, saved, and applied states.
+- A new client receives valid IPv4/IPv6 addresses and a full-tunnel configuration file; the file and QR code represent the same configuration.
+- A new secret is encrypted without a password; reissuing requires the correct password for the selected client.
+- Failed file delivery can be retried during the current creation session.
+- Failure of a mandatory backup prevents the protected operation from proceeding.
+- Restoration without a password returns the archive's saved state without restarting the VPN.
+- A deleted address is not reassigned until a successful restart has been verified.
+- Restart and real server access are tested only in a dedicated environment.

docs/adr/0001-explicit-restart.md

@@ -0,0 +1,3 @@
+# Commit saves files; applying changes requires a separate restart
+
+Adding and removing peers can technically be applied without a restart, but the administrator chose an explicit boundary between saving changes and modifying the running VPN. Therefore, Commit does not trigger a reload or restart; the TUI distinguishes draft, saved, and applied states. A deleted client's address remains reserved until a successful restart has been verified. This is deliberate product behavior rather than a WireGuard limitation.

docs/adr/0002-client-secret-storage.md

@@ -0,0 +1,3 @@
+# New secrets are encrypted without a password; reissuing requires decryption
+
+The application must create new clients without requesting a password and require a password to reissue their private keys. Asymmetric encryption was chosen: the vault's public key is available for writing, while its secret key is password-protected. The vault is backed up and restored as a whole without decryption. Password loss is unrecoverable; this scheme does not encrypt the server configuration, original files, or the entire backup archive.

docs/adr/0003-server-config-authority.md

@@ -0,0 +1,3 @@
+# The server configuration is the source of truth for clients
+
+The installation already contains clients and a manually configured server. To maintain compatibility, the application modifies only client sections and managed comments containing descriptive metadata. All other server settings and comments are preserved. This rules out an independent alias registry as a source of truth and requires parsing that preserves the original document rather than fully reserializing the configuration.