nx9-wg/docs/SECURITY.md

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)