|
|
|
@@ -0,0 +1,300 @@
|
|
|
|
|
# AGENTS.md
|
|
|
|
|
|
|
|
|
|
## Scope
|
|
|
|
|
|
|
|
|
|
- These rules apply to the entire repository.
|
|
|
|
|
- Build a local WireGuard management tool for Linux servers.
|
|
|
|
|
- Keep `wg-manager.sh` as the primary entry point.
|
|
|
|
|
- The project is copied as a directory and is not installed into `PATH`.
|
|
|
|
|
- Do not add installer or uninstaller scripts unless explicitly requested.
|
|
|
|
|
- Treat `MVP.md` as the product scope and acceptance reference.
|
|
|
|
|
- Treat `PLANS.md` as the required milestone sequence for MVP implementation.
|
|
|
|
|
- Complete and verify one milestone before starting the next one.
|
|
|
|
|
- Update the `PLANS.md` progress and execution log as milestones are completed.
|
|
|
|
|
- Run milestones under the Sol coordinator and Luna worker/reviewer loop defined in `PLANS.md` and `.codex/`.
|
|
|
|
|
- The coordinator must independently review Luna's changes and delegate explicit Luna repairs until verification passes or a genuine blocker remains.
|
|
|
|
|
- Use the existing `add-user.sh` only as a behavioral reference.
|
|
|
|
|
- New code must improve its safety rather than copy its weaknesses.
|
|
|
|
|
|
|
|
|
|
## General priorities
|
|
|
|
|
|
|
|
|
|
- Preserve a working WireGuard configuration above all else.
|
|
|
|
|
- Prefer correctness and recoverability over cleverness.
|
|
|
|
|
- Keep CLI behavior independent from the TUI.
|
|
|
|
|
- Make every mutating operation explicit and auditable.
|
|
|
|
|
- Keep secrets out of output, logs, tests, and error messages.
|
|
|
|
|
- Minimize required dependencies.
|
|
|
|
|
- Support operation over SSH and ordinary terminal emulators.
|
|
|
|
|
- Write user-facing text in Russian unless the surrounding interface uses another language.
|
|
|
|
|
- Keep identifiers, functions, CLI command names, and code comments in English.
|
|
|
|
|
- Avoid unrelated refactors while implementing a focused change.
|
|
|
|
|
|
|
|
|
|
## Bash baseline
|
|
|
|
|
|
|
|
|
|
- Use Bash, not POSIX `sh`.
|
|
|
|
|
- Start executable scripts with `#!/usr/bin/env bash`.
|
|
|
|
|
- Enable `set -Eeuo pipefail` in production entry points.
|
|
|
|
|
- Understand strict-mode exceptions before suppressing them.
|
|
|
|
|
- Use `if command; then` when a nonzero status is expected.
|
|
|
|
|
- Do not append `|| true` unless the ignored failure is intentional and documented.
|
|
|
|
|
- Set `umask 077` before creating configs, keys, metadata, logs, or backups.
|
|
|
|
|
- Require a supported Bash version at startup when using version-specific features.
|
|
|
|
|
- Prefer Bash builtins over unnecessary subprocesses.
|
|
|
|
|
- Use `printf` rather than `echo -e`.
|
|
|
|
|
- Use `[[ ... ]]` for Bash conditionals.
|
|
|
|
|
- Use `(( ... ))` for arithmetic conditions.
|
|
|
|
|
- Use `case` for command dispatch and finite state handling.
|
|
|
|
|
- Use `local` for function-local variables.
|
|
|
|
|
- Declare variables close to first use.
|
|
|
|
|
- Use `readonly` for constants after configuration is loaded.
|
|
|
|
|
- Use uppercase names only for exported variables and true constants.
|
|
|
|
|
- Use lowercase snake_case for local variables and functions.
|
|
|
|
|
- Give functions verb-based names such as `load_config` or `add_client`.
|
|
|
|
|
- Keep functions focused and normally below about 60 lines.
|
|
|
|
|
- Return statuses from functions; print data only when output is the contract.
|
|
|
|
|
- Do not mix machine-readable results with progress messages.
|
|
|
|
|
- Send errors and diagnostics to stderr.
|
|
|
|
|
- Use explicit exit codes for expected CLI failure categories.
|
|
|
|
|
|
|
|
|
|
## Quoting and data handling
|
|
|
|
|
|
|
|
|
|
- Double-quote parameter expansions unless splitting is deliberately required.
|
|
|
|
|
- Use `"${array[@]}"` when forwarding array elements.
|
|
|
|
|
- Use arrays to build commands; never construct commands as strings.
|
|
|
|
|
- Never use `eval`.
|
|
|
|
|
- Never pass user-controlled text to `bash -c`.
|
|
|
|
|
- Avoid command substitution for multiline or NUL-sensitive data.
|
|
|
|
|
- Use `mapfile -t` for line-oriented command output when appropriate.
|
|
|
|
|
- Use `IFS= read -r` to read literal lines.
|
|
|
|
|
- Use `read -r -d ''` or NUL delimiters for arbitrary file names.
|
|
|
|
|
- Use `--` before user-derived positional arguments where supported.
|
|
|
|
|
- Do not rely on locale-sensitive parsing.
|
|
|
|
|
- Set `LC_ALL=C` locally for command output that must be parsed predictably.
|
|
|
|
|
- Do not parse human-formatted output when a stable dump format exists.
|
|
|
|
|
- Prefer `wg show <interface> dump` for WireGuard state parsing.
|
|
|
|
|
- Treat names, endpoints, addresses, paths, and config values as untrusted input.
|
|
|
|
|
- Validate input with allowlists and semantic checks.
|
|
|
|
|
- Reject control characters and embedded newlines in user input.
|
|
|
|
|
- Never derive a filesystem path from an unchecked client name.
|
|
|
|
|
- Canonicalize or constrain paths before reading or writing them.
|
|
|
|
|
|
|
|
|
|
## Configuration
|
|
|
|
|
|
|
|
|
|
- Keep server-specific values in `wg-manager.conf`.
|
|
|
|
|
- Resolve the project directory from `${BASH_SOURCE[0]}`.
|
|
|
|
|
- Do not depend on the caller's current working directory.
|
|
|
|
|
- Do not silently overwrite administrator configuration.
|
|
|
|
|
- Validate every required setting at startup.
|
|
|
|
|
- Reject unknown enum values such as unsupported tunnel modes.
|
|
|
|
|
- Validate numeric ranges before arithmetic use.
|
|
|
|
|
- Validate IPv4, IPv6, CIDR, port, and hostname values before use.
|
|
|
|
|
- Do not `source` a configuration file that may be writable by untrusted users.
|
|
|
|
|
- If sourcing is retained, require root ownership and non-group/world-writable permissions.
|
|
|
|
|
- Prefer a restricted `KEY=VALUE` parser for long-term safety.
|
|
|
|
|
- Environment overrides must be documented and narrowly scoped.
|
|
|
|
|
- Never accept key material through command-line arguments.
|
|
|
|
|
- Avoid exporting secrets into the process environment.
|
|
|
|
|
|
|
|
|
|
## Temporary files and cleanup
|
|
|
|
|
|
|
|
|
|
- Create temporary files with `mktemp`.
|
|
|
|
|
- Create mutation staging files on the same filesystem as the target.
|
|
|
|
|
- Never use predictable temporary filenames.
|
|
|
|
|
- Register cleanup immediately after creating temporary resources.
|
|
|
|
|
- Use a cleanup function with `trap` for `EXIT`, `INT`, and `TERM`.
|
|
|
|
|
- Quote trap bodies safely; avoid premature expansion.
|
|
|
|
|
- Preserve the original exit status during cleanup.
|
|
|
|
|
- Do not remove a path unless this process created it or validated it exactly.
|
|
|
|
|
- Apply restrictive permissions before writing secret content.
|
|
|
|
|
- Do not leave key material in world-readable temporary directories.
|
|
|
|
|
|
|
|
|
|
## WireGuard safety
|
|
|
|
|
|
|
|
|
|
- Require root only for commands that need privileged access or mutation.
|
|
|
|
|
- Allow safe read-only commands without root when system permissions permit it.
|
|
|
|
|
- Check that the configured interface and config file agree.
|
|
|
|
|
- Identify peers by public key, not only by display name.
|
|
|
|
|
- Treat comments such as `### Client NAME` as metadata, not identity.
|
|
|
|
|
- Detect duplicate public keys and overlapping `AllowedIPs`.
|
|
|
|
|
- Detect address collisions before generating any persistent file.
|
|
|
|
|
- Distinguish managed peers from unmanaged peers.
|
|
|
|
|
- Never modify an unmanaged peer implicitly.
|
|
|
|
|
- Do not regenerate server keys automatically.
|
|
|
|
|
- Do not rotate or replace client keys without explicit confirmation.
|
|
|
|
|
- Never print private or preshared keys in routine output.
|
|
|
|
|
- Never include key values in traces or debug logs.
|
|
|
|
|
- Disable shell tracing around all secret-handling code.
|
|
|
|
|
- Store client files with mode `0600`.
|
|
|
|
|
- Keep directories containing client material at mode `0700`.
|
|
|
|
|
|
|
|
|
|
## Mutating operations
|
|
|
|
|
|
|
|
|
|
- Serialize mutations with `flock`.
|
|
|
|
|
- Acquire the lock before re-reading mutable state.
|
|
|
|
|
- Revalidate assumptions after the lock is acquired.
|
|
|
|
|
- Create a backup before every persistent change.
|
|
|
|
|
- Write the complete proposed config to a staging file.
|
|
|
|
|
- Validate the staged config before replacing the live config.
|
|
|
|
|
- Preserve the target owner, group, and restrictive mode.
|
|
|
|
|
- Replace files atomically with a same-filesystem rename.
|
|
|
|
|
- Apply the new configuration only after durable storage succeeds.
|
|
|
|
|
- Verify active state after applying the change.
|
|
|
|
|
- Roll back both disk and runtime state on failure.
|
|
|
|
|
- Report rollback failure as a critical error.
|
|
|
|
|
- Never append directly to the live WireGuard config.
|
|
|
|
|
- Never use broad text deletion to remove a peer block.
|
|
|
|
|
- Match an exact managed block and its public key.
|
|
|
|
|
- Default to archiving client files instead of permanent deletion.
|
|
|
|
|
- Require explicit confirmation before destructive or restorative actions.
|
|
|
|
|
- Make repeated operations fail safely or behave idempotently.
|
|
|
|
|
|
|
|
|
|
## Backups and audit log
|
|
|
|
|
|
|
|
|
|
- Timestamp backups in an unambiguous UTC format.
|
|
|
|
|
- Include the interface name in backup metadata or filenames.
|
|
|
|
|
- Keep a bounded number of automatic backups.
|
|
|
|
|
- Never prune the only known-good backup.
|
|
|
|
|
- Validate a backup before offering restoration.
|
|
|
|
|
- Back up the current state before restoring an older state.
|
|
|
|
|
- Record who initiated a mutation when that information is available.
|
|
|
|
|
- Log the operation, target, timestamp, outcome, and concise error.
|
|
|
|
|
- Do not log private keys, preshared keys, or full client configs.
|
|
|
|
|
- Avoid logging full environment dumps or command lines with secrets.
|
|
|
|
|
- Make logs readable only by root by default.
|
|
|
|
|
- Log failed mutations and rollback outcomes.
|
|
|
|
|
|
|
|
|
|
## CLI design
|
|
|
|
|
|
|
|
|
|
- TUI actions must call the same backend functions as CLI commands.
|
|
|
|
|
- Keep CLI commands usable when `gum` is unavailable.
|
|
|
|
|
- Provide `help` and useful usage errors.
|
|
|
|
|
- Reject unknown commands and extra positional arguments.
|
|
|
|
|
- Keep command names stable once documented.
|
|
|
|
|
- Use stdout for requested data and stderr for warnings or progress.
|
|
|
|
|
- Do not add decorative ANSI output when stdout is not a terminal.
|
|
|
|
|
- Honor `NO_COLOR` for CLI colors where colors are used.
|
|
|
|
|
- Return zero only when the requested operation succeeded.
|
|
|
|
|
- Use distinct nonzero statuses for usage, validation, dependency, and runtime errors.
|
|
|
|
|
- Avoid interactive prompts when a CLI command is explicitly noninteractive.
|
|
|
|
|
- Require a confirmation flag for destructive noninteractive commands.
|
|
|
|
|
- Never let localization change machine-parsed values or exit codes.
|
|
|
|
|
|
|
|
|
|
## TUI with gum
|
|
|
|
|
|
|
|
|
|
- Use `gum` as the only planned TUI framework.
|
|
|
|
|
- Do not add `dialog`, `whiptail`, or a second TUI framework.
|
|
|
|
|
- Do not download or install `gum` from the application.
|
|
|
|
|
- Resolve `gum` in this order: `WG_MANAGER_GUM`, local `bin/gum`, then `PATH`.
|
|
|
|
|
- Validate that the resolved path is executable.
|
|
|
|
|
- Check required `gum` subcommands or minimum version at startup.
|
|
|
|
|
- Fail with a clear message when TUI is requested without usable `gum`.
|
|
|
|
|
- Keep all `gum` invocation details in small UI wrapper functions.
|
|
|
|
|
- Backend functions must never call `gum` directly.
|
|
|
|
|
- Use `gum choose` for short finite menus.
|
|
|
|
|
- Use `gum filter` for searchable client selection.
|
|
|
|
|
- Use `gum input` for short validated text fields.
|
|
|
|
|
- Use `gum confirm` before deletion, restoration, or key rotation.
|
|
|
|
|
- Use `gum table` only for display or selection, not as a data store.
|
|
|
|
|
- Use `gum pager` for logs, diagnostics, and long text.
|
|
|
|
|
- Use `gum spin` only when the wrapped operation can safely hide routine output.
|
|
|
|
|
- Preserve stderr from failed commands behind a spinner.
|
|
|
|
|
- Never show secret content inside a spinner command line.
|
|
|
|
|
- Keep stable internal values separate from translated display labels.
|
|
|
|
|
- Treat cancellation and Escape as normal control flow, not an error.
|
|
|
|
|
- Return to the previous screen after cancellation.
|
|
|
|
|
- Do not trap users in an endless menu loop after repeated failures.
|
|
|
|
|
- Keep the main menu shallow and task-oriented.
|
|
|
|
|
- Show interface name and current status on the main screen.
|
|
|
|
|
- Use consistent verbs: view, add, remove, diagnose, restore, exit.
|
|
|
|
|
- Show the exact target before asking for destructive confirmation.
|
|
|
|
|
- Require stronger confirmation for restoring backups or deleting client material.
|
|
|
|
|
- Keep colors readable on light and dark terminals.
|
|
|
|
|
- Do not communicate status by color alone.
|
|
|
|
|
- Keep layouts usable at 80 columns.
|
|
|
|
|
- Avoid assumptions about mouse support.
|
|
|
|
|
- Do not clear valuable terminal output after an error.
|
|
|
|
|
- Detect noninteractive stdin or stdout before starting TUI.
|
|
|
|
|
- Never emit TUI control output into pipelines or redirected files.
|
|
|
|
|
|
|
|
|
|
## Error handling
|
|
|
|
|
|
|
|
|
|
- Provide one concise user-facing error plus actionable context.
|
|
|
|
|
- Preserve the failing command's status where meaningful.
|
|
|
|
|
- Do not expose secret variable values in error messages.
|
|
|
|
|
- Distinguish validation errors from system failures.
|
|
|
|
|
- Distinguish skipped diagnostic checks from successful checks.
|
|
|
|
|
- Diagnostic results use `OK`, `WARN`, `FAIL`, or `SKIP`.
|
|
|
|
|
- A critical diagnostic failure must produce a nonzero status.
|
|
|
|
|
- Include remediation guidance when it is reliable and specific.
|
|
|
|
|
- Avoid guessing firewall fixes across distributions.
|
|
|
|
|
- Continue independent diagnostic checks after a nonfatal failure.
|
|
|
|
|
|
|
|
|
|
## Dependencies and portability
|
|
|
|
|
|
|
|
|
|
- Assume a Linux server with Bash and WireGuard tools.
|
|
|
|
|
- Keep required dependencies listed in `MVP.md` and README.
|
|
|
|
|
- Treat `qrencode`, systemd, `nft`, and `iptables` as optional capabilities.
|
|
|
|
|
- Detect optional commands before using them.
|
|
|
|
|
- Do not fail the entire diagnostic run because one optional tool is absent.
|
|
|
|
|
- Prefer feature detection over distribution detection.
|
|
|
|
|
- Do not assume systemd is PID 1 on every supported server.
|
|
|
|
|
- Support at least Linux `x86_64`; document additional tested architectures.
|
|
|
|
|
- Do not assume the bundled `gum` binary matches the current architecture.
|
|
|
|
|
- Report architecture mismatch clearly.
|
|
|
|
|
|
|
|
|
|
## Tests
|
|
|
|
|
|
|
|
|
|
- Add regression tests for every fixed bug.
|
|
|
|
|
- Tests must not modify the host's real `/etc/wireguard`.
|
|
|
|
|
- Use fixtures for server configs, peer blocks, and metadata.
|
|
|
|
|
- Mock external commands through a controlled test `PATH`.
|
|
|
|
|
- Cover `wg`, `wg-quick`, `ip`, `systemctl`, `journalctl`, `nft`, and `iptables` as needed.
|
|
|
|
|
- Test success, expected failure, rollback, and interruption paths.
|
|
|
|
|
- Test client names containing spaces, newlines, glob characters, and option prefixes.
|
|
|
|
|
- Test duplicate keys, duplicate IPs, and overlapping networks.
|
|
|
|
|
- Test empty peer lists and unmanaged peers.
|
|
|
|
|
- Test CLI behavior without `gum`.
|
|
|
|
|
- Test local binary, environment override, and `PATH` resolution for `gum`.
|
|
|
|
|
- Test that logs do not contain generated secrets.
|
|
|
|
|
- Test concurrent mutation attempts.
|
|
|
|
|
- Test restoration failure and failed rollback reporting.
|
|
|
|
|
- Keep tests deterministic; do not depend on external network access.
|
|
|
|
|
- Use temporary test directories and remove them safely.
|
|
|
|
|
|
|
|
|
|
## Quality gates
|
|
|
|
|
|
|
|
|
|
- Run `bash -n` on every changed shell script.
|
|
|
|
|
- Run ShellCheck on every changed shell script when available.
|
|
|
|
|
- Run the relevant automated tests.
|
|
|
|
|
- Format consistently; use `shfmt` when the project adopts a fixed style.
|
|
|
|
|
- Do not silence ShellCheck globally to hide local problems.
|
|
|
|
|
- Add a narrow inline suppression only with an explanatory comment.
|
|
|
|
|
- Review diffs for accidental key material before finishing.
|
|
|
|
|
- Review file permissions in tests that create secrets.
|
|
|
|
|
- Verify that failure paths preserve the original config.
|
|
|
|
|
- Verify CLI output with stdout redirected.
|
|
|
|
|
- Verify TUI entry and cancellation in an interactive terminal.
|
|
|
|
|
|
|
|
|
|
## Documentation
|
|
|
|
|
|
|
|
|
|
- Update `MVP.md` only when product scope or architecture changes.
|
|
|
|
|
- Keep operational usage in README once implementation begins.
|
|
|
|
|
- Document every CLI command and its exit behavior.
|
|
|
|
|
- Document required and optional dependencies separately.
|
|
|
|
|
- Include examples that use placeholder keys and addresses only.
|
|
|
|
|
- Never commit real endpoints, private keys, preshared keys, or client configs.
|
|
|
|
|
- Explain backup and restore behavior before users rely on it.
|
|
|
|
|
- Document limitations of handshake history and traffic visibility.
|
|
|
|
|
|
|
|
|
|
## Definition of done
|
|
|
|
|
|
|
|
|
|
- The requested behavior is implemented through shared backend functions.
|
|
|
|
|
- Mutations are locked, validated, backed up, atomic, and reversible.
|
|
|
|
|
- CLI operation remains available independently of the TUI.
|
|
|
|
|
- TUI uses the configured `gum` resolution order.
|
|
|
|
|
- Errors are actionable and do not reveal secrets.
|
|
|
|
|
- Relevant tests pass.
|
|
|
|
|
- `bash -n` passes.
|
|
|
|
|
- ShellCheck has no unexplained findings.
|
|
|
|
|
- Documentation matches observable behavior.
|
|
|
|
|
- No unrelated files or user changes are overwritten.
|
