# 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`.
- **Upstream Import Secret Safety**: Third-party `.conf` previews and import responses never return private keys or preshared keys in cleartext. Sensitive keys are stored strictly in the database and submitted to the kernel over Netlink.
- **Reconciliation Plan & Report Scrubbing**: Dry-run plans and reconciliation convergence reports scrub private keys and preshared keys to prevent accidental leakage into logs or event streams.
- **SPA CLI Console Output Sanitization**: The read-only SPA CLI execution endpoint runs an automated secret scrubber over command outputs, stripping private keys and credentials before returning output to the browser.
- Web UI and REST API responses redact private keys and token hashes.
- CLI status output strictly redacts sensitive cryptographic keys and password 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`)