# 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`)