nx9-wg/docs/security.md

Security Model and Best Practices

nx9-wg implements a strict, self-hosted, fail-closed security architecture.

---

1. Single Administrator Identity

• Fixed Database Identity: The administrative record in SQLite is locked with CHECK (id = 1).
• No RBAC or Multi-Tenancy: Eliminates attack surface from privilege escalation, permission bypasses, or broken object-level authorization.
• Argon2id Password Hashing: State-of-the-art memory-hard password derivation (argon2id). Plaintext passwords are never stored in memory longer than verification duration and never written to disk or logs.

---

2. Token and Session Security

• Hashed API Tokens: API tokens use the nx9_<base64> format. Only the SHA-256 cryptographic digest of the token is persisted in SQLite. Compromise of the database does not reveal plaintext API tokens.
• Global Session Invalidation: When the administrator changes their password, all active sessions across all devices are immediately invalidated in SQLite.
• HttpOnly Cookies: Session tokens sent to browsers use HttpOnly, SameSite=Strict, and Secure (when TLS is active).

---

3. Brute-Force Rate Limiting

• nx9-wg maintains an append-only tracking log of login attempts in SQLite.
• If more than 5 failed authentication attempts originate from the same IP address within a 15-minute sliding window, subsequent login requests are rejected with HTTP 429 Too Many Requests.

---

4. Secret Handling and Memory Safety

• Redacted Debug Outputs: Types holding sensitive material (WireGuardPrivateKey, WireGuardPresharedKey, Admin, ApiToken) implement custom std::fmt::Debug formatters outputting [REDACTED].
• No Plaintext Logging: Secrets are strictly excluded from structured tracing event spans.

---

5. Audit Logging

Every state-changing operation records an append-only audit event:

• Authentication (Login, Logout, LoginFailed)
• Credential Lifecycle (PasswordChange, TotpChange, ApiTokenCreate, ApiTokenRevoke)
• Network & WireGuard (InterfaceCreate, PeerCreate, PeerRotateKeys, RouteCreate, FirewallCreate)
• System Operations (BackupCreate, BackupRestore, ReconciliationRun)