Clean up documentation structure and links

2026-08-30 20:02:38 +05:30
1 parent d25846c58c
commit 32a325234a
@@ -0,0 +1,71 @@
+# Security Model, Privilege Architecture & Best Practices
+
+`nx9-wg` is designed with a strict, defense-in-depth, fail-closed security architecture tailored for self-hosted sovereign network infrastructure.
+
+---
+
+## 1. Single Administrator Identity Model
+
+- **Database-Level Constraint**: The administrative record in SQLite is locked with `CHECK (id = 1)`.
+- **Zero Multi-Tenancy / RBAC Attack Surface**: Eliminates privilege escalation, role confusion, and broken object-level authorization vulnerabilities.
+- **Argon2id Password Hashing**: State-of-the-art memory-hard password derivation (`argon2id`). Passwords are never stored in plaintext, never logged, and never included in error responses.
+- **One-Time Credential Delivery**: Generated passwords and raw API tokens are displayed exactly once upon creation (or written to explicit 0600-permission files) and cannot be recovered from the database.
+
+---
+
+## 2. API Token and Session Architecture
+
+- **Cryptographically Hashed Tokens**: API tokens follow the format `nx9_<uuid>_<random>`. Only the SHA-256 digest of the token (`token_hash`) is stored in SQLite. Database exfiltration will not compromise raw API tokens.
+- **Global Session Invalidation**: Changing the administrator password automatically invalidates all active browser sessions across all devices.
+- **Secure Cookie Flags**: Session cookies use `HttpOnly`, `SameSite=Strict`, and `Path=/`.
+- **Brute-Force Rate Limiting**: Exponential backoff and IP-based rate limiting (5 failed attempts per 15-minute sliding window triggers `HTTP 429 Too Many Requests`).
+
+---
+
+## 3. Filesystem Permissions Matrix
+
+| Path | Standard Owner | File Mode | Purpose / Security Scope |
+| :--- | :--- | :--- | :--- |
+| `/usr/local/bin/nx9-wg` | `root:root` | `0755` | Executable binary |
+| `/etc/nx9-wg/` | `root:root` | `0750` | Configuration directory |
+| `/etc/nx9-wg/config.toml` | `root:root` | `0640` | Production configuration file |
+| `/var/lib/nx9-wg/` | `root:root` | `0700` | Working directory and SQLite database storage |
+| `/var/lib/nx9-wg/nx9-wg.db` | `root:root` | `0600` | Authoritative SQLite database with WAL journals |
+| `/var/lib/nx9-wg/backups/` | `root:root` | `0700` | Atomic SQLite database snapshots and checksum manifests |
+| `/var/lib/nx9-wg/admin-password`| `root:root` | `0600` | Initial generated password file |
+| `/var/log/nx9-wg/` | `root:root` | `0750` | Operational logs (if file logging enabled) |
+
+---
+
+## 4. Zero Subprocess Execution Guarantee
+
+`nx9-wg` strictly forbids external subprocess execution in production:
+- **No `std::process::Command` / `tokio::process`**: Eliminates command injection, shell escaping vulnerabilities, and PATH hijack risks.
+- **No External CLI Dependencies**: Does not shell out to `wg`, `ip`, `nft`, `iptables`, `sysctl`, or `bash`.
+- **Direct Kernel Communication**: Communicates via native Linux Netlink sockets (RTNETLINK and WireGuard Generic Netlink) and direct in-process `libnftables` Netfilter bindings.
+
+---
+
+## 5. nftables Scoping & Firewall Isolation
+
+- **Table Isolation**: All rules and chains are strictly confined to `table inet nx9_wg`.
+- **Zero Interference**: `nx9-wg` never flushes or modifies external tables created by Docker, Kubernetes, systemd-networkd, or host firewalls.
+- **Deterministic Priority Rules**: Chains and rules are ordered deterministically by priority index to prevent rule shadowing or accidental packet leaks.
+
+---
+
+## 6. Secret Redaction & Memory Safety
+
+- Custom `std::fmt::Debug` implementations enforce `[REDACTED]` for `WireGuardPrivateKey`, `WireGuardPresharedKey`, `Admin`, and `ApiToken`.
+- Web UI and REST API responses redact private keys and token hashes.
+- CLI status output strictly redacts sensitive hashes.
+
+---
+
+## 7. Append-Only Security Audit Logging
+
+Every state mutation records an append-only audit event with timestamp, actor, IP address, event type, and context metadata:
+- Authentication events (`Login`, `Logout`, `LoginFailed`)
+- Credential modifications (`PasswordChange`, `ApiTokenCreate`, `ApiTokenRevoke`)
+- WireGuard & Network configurations (`InterfaceCreate`, `PeerCreate`, `RouteCreate`, `FirewallCreate`)
+- System operations (`BackupCreate`, `BackupRestore`, `ReconciliationRun`)