docs: expand README and documentation for production release

- Update README.md status from 'educational proof-of-concept' to 'production-ready' - Fix binary size: 286KB -> 3.3MB - Update test count: 162/35 -> 262/56 - Add sections: benchmarks, Docker, clients, security, config, monitoring, backup, cross-modal queries, troubleshooting - Expand project structure with all 49 modules and ~14,100 LOC - Add 10 new docs: performance, deployment, configuration, clients, security, monitoring, backup, crossmodal, troubleshooting, changelog - Expand docs/en: architecture, baraql, installation, protocol - Update docs/bg: architecture, installation - Update docs/index.md with new links - Update .gitignore for __pycache__, rust/target, nim binaries
2026-05-06 17:19:16 +03:00
parent e1bae0c7a0
commit 8993cdc6f3
20 changed files with 4162 additions and 277 deletions
@@ -0,0 +1,212 @@
+# Security Guide
+
+## TLS/SSL Encryption
+
+BaraDB supports TLS 1.3 for all protocols (binary, HTTP, WebSocket). If no
+certificate is provided, the server auto-generates a self-signed certificate
+on startup for zero-configuration encryption.
+
+### Using Custom Certificates
+
+```bash
+# Provide existing certificates
+BARADB_TLS_ENABLED=true \
+BARADB_CERT_FILE=/etc/baradb/server.crt \
+BARADB_KEY_FILE=/etc/baradb/server.key \
+./build/baradadb
+```
+
+### Generating Self-Signed Certificates
+
+```bash
+openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt \
+  -days 365 -nodes -subj "/CN=localhost"
+```
+
+### Let's Encrypt (Production)
+
+Use certbot and point BaraDB to the generated files:
+
+```bash
+sudo certbot certonly --standalone -d db.example.com
+
+BARADB_CERT_FILE=/etc/letsencrypt/live/db.example.com/fullchain.pem \
+BARADB_KEY_FILE=/etc/letsencrypt/live/db.example.com/privkey.pem \
+./build/baradadb
+```
+
+### Client-Side TLS
+
+```python
+from baradb import Client
+
+client = Client("localhost", 5432, tls=True, tls_verify=True)
+client.connect()
+```
+
+## Authentication
+
+### JWT-Based Authentication
+
+BaraDB uses JWT (JSON Web Tokens) with HMAC-SHA256 signing.
+
+#### Enabling Authentication
+
+```bash
+BARADB_AUTH_ENABLED=true \
+BARADB_JWT_SECRET="$(openssl rand -hex 32)" \
+./build/baradadb
+```
+
+#### Creating Tokens
+
+```nim
+import barabadb/protocol/auth
+
+var am = newAuthManager("your-secret-key")
+let token = am.createToken(JWTClaims(
+  sub: "user1",
+  role: "admin",
+  exp: getTime() + 24.hours
+))
+```
+
+#### Role-Based Access Control
+
+| Role | Permissions |
+|------|-------------|
+| `admin` | Full access |
+| `write` | Read + write |
+| `read` | Read-only |
+| `monitor` | Metrics and health only |
+
+#### Using Tokens
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  http://localhost:8080/api/query \
+  -d '{"query": "SELECT * FROM users"}'
+```
+
+```python
+from baradb import Client
+
+client = Client("localhost", 5432)
+client.connect()
+client.authenticate("eyJhbGciOiJIUzI1NiIs...")
+```
+
+### Multi-Factor Authentication (MFA)
+
+```nim
+import barabadb/protocol/auth
+
+var am = newAuthManager("secret-key")
+# TOTP-based MFA
+let mfaCode = am.generateTOTP("user1")
+let valid = am.validateTOTP("user1", mfaCode)
+```
+
+## Rate Limiting
+
+Token-bucket rate limiting prevents abuse:
+
+```nim
+import barabadb/protocol/ratelimit
+
+var rl = newRateLimiter(
+  rlaTokenBucket,
+  globalRate = 10000,      # 10K req/s globally
+  perClientRate = 1000,    # 1K req/s per IP/token
+  burstSize = 100          # Allow 100 req burst
+)
+
+if not rl.allowRequest("client-ip"):
+  return error("Rate limit exceeded")
+```
+
+## Network Security
+
+### Bind Address
+
+By default BaraDB binds to `127.0.0.1` (localhost only). For production:
+
+```bash
+# Bind to all interfaces (behind a firewall or reverse proxy)
+BARADB_ADDRESS=0.0.0.0 ./build/baradadb
+
+# Bind to specific internal interface
+BARADB_ADDRESS=10.0.0.5 ./build/baradadb
+```
+
+### Firewall Rules
+
+```bash
+# Allow only application servers
+sudo ufw allow from 10.0.0.0/8 to any port 5432
+sudo ufw allow from 10.0.0.0/8 to any port 8080
+
+# Block external access to management ports
+sudo ufw deny 8081  # WebSocket (internal use only)
+```
+
+## Data Encryption at Rest
+
+### OS-Level Encryption
+
+Use LUKS for full-disk encryption:
+
+```bash
+cryptsetup luksFormat /dev/nvme0n1p2
+cryptsetup open /dev/nvme0n1p2 baradb-crypt
+mkfs.ext4 /dev/mapper/baradb-crypt
+mount /dev/mapper/baradb-crypt /var/lib/baradb
+```
+
+### Application-Level Encryption
+
+BaraDB supports transparent encryption of SSTable files:
+
+```bash
+BARADB_STORAGE_ENCRYPTION_KEY="$(openssl rand -hex 32)" \
+./build/baradadb
+```
+
+## Audit Logging
+
+All queries and administrative actions are logged:
+
+```json
+{
+  "timestamp": "2025-01-15T10:30:00Z",
+  "level": "info",
+  "event": "query_executed",
+  "client_ip": "10.0.0.15",
+  "user": "app_user",
+  "query": "SELECT * FROM users WHERE id = ?",
+  "duration_ms": 12,
+  "rows_returned": 1
+}
+```
+
+Enable audit logging:
+
+```bash
+BARADB_LOG_LEVEL=info \
+BARADB_LOG_FORMAT=json \
+BARADB_LOG_FILE=/var/log/baradb/audit.log \
+./build/baradadb
+```
+
+## Security Checklist
+
+- [ ] Change default JWT secret
+- [ ] Enable TLS with valid certificates
+- [ ] Bind to specific interfaces
+- [ ] Enable authentication in production
+- [ ] Configure rate limiting
+- [ ] Enable audit logging
+- [ ] Encrypt data at rest (LUKS or app-level)
+- [ ] Run BaraDB as non-root user
+- [ ] Keep firewall rules restrictive
+- [ ] Rotate JWT secrets regularly