teknav-bak/app/SECURITY.md

# Security — Teknav

Summary of security measures across the stack.

---

## Nginx

### HTTP Security Headers
- `Strict-Transport-Security` (HSTS) — 1 year (`max-age=31536000; includeSubDomains`)
- `Content-Security-Policy` — self-only scripts/styles/fonts; `data:` and `blob:` for inline images; no CDN
- `X-Content-Type-Options: nosniff`
- `X-Frame-Options: SAMEORIGIN`
- `Referrer-Policy: strict-origin-when-cross-origin`
- `Permissions-Policy: camera=(), microphone=(), geolocation=()`

### Rate Limiting (tuned to avoid false 429s)
| Zone | Rate | Burst | Targets |
|---|---|---|---|
| `general` | 300 r/min | 200 | SPA routes |
| `api` | 300 r/min | 200 | All `/api/*` |
| `auth` | 30 r/min | 10 | `/api/v1/auth/login`, `/api/v1/auth/signup` |

Fastify applies its own per-IP counters on top (5 login fails / 15 min; 10 signup attempts / hour).

### Blocked Paths
- Dotfiles: `.git`, `.env`, `.htaccess`, etc.
- Operator credential file: `/ACCOUNTS.md`
- Upload directory: blocks `.php/.html/.js/.sh/.py/.env/.conf` execution

### Proxy Hardening
- `Server` and `X-Powered-By` headers stripped
- `server_tokens off`
- Connection timeouts: 30s client, 10s proxy connect, 60s proxy read
- `trustProxy` constrained to `['127.0.0.1', '::1']` — only the local nginx proxy is trusted

### Error Handling
- 404 → SPA fallback (`/index.html`) for client-side routing
- 429 → JSON `{"error":"too_many_requests","retryAfter":60}`
- 5xx → JSON `{"error":"service_unavailable"}`
- 400/401/403 from `/api/*` pass through as-is (JSON from Fastify)

---

## Backend (Fastify)

### Authentication
- **Argon2id** password hashing (m=19 MiB, t=2, p=1)
- Login accepts email or `@username`; password verification stays Argon2id-backed
- Anti-enumeration: constant-time login regardless of whether the user exists
- **Redis-backed sessions** — `tek_sid` cookie (HttpOnly, Secure, SameSite=Lax), 14-day TTL with sliding expiration
- **Session rotation** — new session ID issued on login and 2FA completion to prevent session fixation
- **Session invalidation on password change** — all sessions for a user are destroyed when their password is updated (via reset, profile, or admin)
- **CSRF** — double-submit cookie pattern (`tek_csrf`); required on all mutating routes except `/api/v1/auth/login`, `/api/v1/auth/signup`, `/api/v1/auth/forgot-password`, `/api/v1/auth/reset-password`, `/api/v1/auth/otp/send`, `/api/v1/auth/otp/verify`, `/api/v1/auth/2fa/verify`, `/api/v1/newsletter`, `/api/v1/analytics/events`, `/api/v1/errors`, `/api/v1/jobs`, and OAuth callbacks (`/api/v1/auth/oauth/*`)
- **OAuth** — Google and GitHub (authorization-code grant); state token stored in Redis (10-min TTL, one-time use); no client secret exposed to frontend

### Rate Limiting (application layer)
- Global Fastify rate limiting on public API traffic (600 requests / IP / min, Redis-backed, per-IP key)
- Route-level exceptions for OAuth callbacks, health, and explicit public-mutating endpoints
- Login: 5 failures / IP / 15 min → 429 + `Retry-After`
- Signup: 10 attempts / IP / hour → 429 + `Retry-After`
- Captcha generate: 20 / IP / min
- Captcha verify: 10 / IP / min
- Newsletter: 3 / IP / hour
- 2FA verify: 5 attempts / IP+ticket / 5 min → 429
- Forgot-password: 5 / IP / hour
- Reset-password: 10 / IP / hour
- Error reporting: 30 / IP / min
- Semantic search: 10 / IP / min

### Input Validation
- Zod schemas on every route (including admin author CRUD)
- Fastify JSON-Schema validation (AJV) on all body/querystring
- Content length limits: wiki proposals (500 KB), glossary definitions (50 KB), comments (1000 chars), article body (no upper bound)

### Role-Based Access Control
| Role | Access |
|---|---|
| `reader` | View articles, save, react, manage own profile |
| `reviewer` | + Article review queue |
| `writer` | + Create/edit own articles |
| `editor` | + Edit any article, manage categories/tags/authors/media/newsletter/series |
| `admin` | + Delete articles, manage users, activity logs, metrics |

### Engagement Controls
- Comment moderation supports bulk approve/delete actions for editors/admins and keeps replies sorted by upvotes.
- Comments require an authenticated session; backend strips HTML and limits body length to 1000 chars.
- Comment flagging is idempotent per user through a compound unique constraint.
- Reading history, notifications, and writer follows are scoped to the current session.
- Notification and admin SSE streams require normal cookie auth; nginx disables buffering/compression only for stream paths.

### Credential Storage
- 2FA login uses Kavenegar OTP (6-digit code via `crypto.randomInt()`), and the verify endpoint is ticket-based with max 3 attempts.
- Staff credentials live in `backend/prisma/credentials.json` (committed, plaintext)
- Operator-facing credential sheet lives in `ACCOUNTS.md` (gitignored and nginx-blocked)
- `seed.ts` hashes them with Argon2id before DB insert — **never** stored plaintext in Postgres
- The three writer-admin accounts use `resetPasswordOnSeed: true` until production rotation is complete
- Rotate via the admin panel before go-live
- After rotation, users can change their own password from profile settings; existing-password accounts must provide the current password
- Public registrations: `reader` role, Argon2id-hashed password (or OAuth — no password stored)
- Admin-created users receive a cryptographically random 24-byte password (not a predictable default)

---

## Database (PostgreSQL)

- Bind PostgreSQL to localhost only; do not expose it publicly
- `passwordHash` — Argon2id only
- `User.status` enum — `active`, `suspended`, `pending`; suspended users are rejected at login
- OAuth fields (`oauthProvider`, `oauthSubject`) use a composite unique index to prevent duplicate linking
- All queries via Prisma ORM — no raw SQL, no `$queryRawUnsafe`, no SQL injection surface

---

## Redis

- Bind Redis to localhost only; do not expose it publicly
- AOF + RDB persistence
- Used for: sessions, CSRF tokens, rate limiting counters, OTP codes, OAuth state, SSE pub/sub, visitor counters

---

## Linux/systemd

- Backend runs as the dedicated `teknav` system user, not root
- `teknav-backend.service` reads secrets from `/etc/teknav/backend.env`
- Upload writes are restricted to `/var/lib/teknav/uploads`
- Timers handle scheduled publishing and daily database backups
- Redis pub/sub backs SSE notifications and admin live counters; Redis must remain private to localhost
- Port 3010 (Fastify) should be firewalled to localhost only; `trustProxy` only trusts `127.0.0.1` and `::1`

---

## Build
- After schema changes, also run `cd backend && npm run build` and `cd backend && npm test`.

- **Zero CDN** — `scripts/check-no-cdn.mjs` greps `dist/` for external domains; build fails on any match
- **Production preflight** — `npm run preflight:prod` checks env templates, nginx SSE/credential protection, required scripts, and generated-engine safety before deployment.
- **Strict endpoint tests** — `cd backend && TEST_REQUIRE_SERVER=1 npm test` forces API contract tests against a running backend; without the env var, tests skip endpoint assertions if no backend is reachable.
- Run `npm audit` and `cd backend && npm audit` before each deploy
- Body size limit: 1 MB global, 25 MB on admin upload routes

---

## Health And Readiness

- `GET /api/v1/health` — returns minimal `{ ok: true/false }` for public load balancers and monitors
- `GET /api/v1/ready` — returns `{ ok: true }` or HTTP 503 when PostgreSQL or Redis is unavailable
- `GET /api/v1/admin/health` — full diagnostics (PostgreSQL connections, Redis memory, feature flags, upload disk, version, uptime); **admin-only**, requires authenticated session
- Neither public endpoint exposes credentials, keys, DSNs, or user data.

---

## Pre-Deploy Checklist

- [ ] `/etc/teknav/backend.env` configured (`SESSION_SECRET` ≥ 32 chars, strong DB password)
- [ ] TLS issued for `www.teknav.ir` and `teknav.ir`
- [ ] `nginx/nginx.conf` updated with real `server_name` + cert paths
- [ ] OAuth `GOOGLE_CLIENT_ID/SECRET` and/or `GITHUB_CLIENT_ID/SECRET` set if using OAuth
- [ ] `OAUTH_CALLBACK_BASE` set to `https://www.teknav.ir`
- [ ] SMTP vars set for password reset and email verification
- [ ] `SMS_PROVIDER=kavenegar` and `SMS_API_KEY` set for phone OTP
- [ ] Credentials in `credentials.json` rotated (via admin UI after first login)
- [ ] `ACCOUNTS.md` is not committed and `curl -I https://www.teknav.ir/ACCOUNTS.md` returns 404/403
- [ ] Remove `resetPasswordOnSeed` after rotating writer-admin passwords if future seeds must not reset them
- [ ] `npm run preflight:prod` passes, with only accepted migration-readiness warnings
- [ ] `npm run build` passes (no CDN refs)
- [ ] `cd backend && npm run build` passes
- [ ] `cd backend && npm audit` shows 0 vulnerabilities
- [ ] `sudo systemctl status teknav-backend` is healthy
- [ ] `curl https://www.teknav.ir/api/v1/health` → 200 `{"ok":true}`
- [ ] `curl https://www.teknav.ir/api/v1/ready` → 200 when PostgreSQL and Redis are healthy
- [ ] Test login at `https://www.teknav.ir/login`
- [ ] Test user signup at `https://www.teknav.ir/login` → signup tab
- [ ] Test authenticated comment, flag, history, follow, and notification flows
- [ ] Test `/api/v1/admin/stream` while logged in as admin/editor
- [ ] Verify `curl https://www.teknav.ir/api/v1/admin/health` requires authentication

---

## Known Limitations

- **Email/SMS depend on production providers** — verification routes are implemented, but delivery requires configured SMTP and Kavenegar credentials
- **`unsafe-inline` on `style-src`** — required by Vite CSS-in-JS injection; harmless (affects styles, not scripts)
- **Session invalidation scans all Redis session keys** — efficient for current scale; if session count grows significantly, consider a `passwordChangedAt` field approach instead
- **Global rate limit `skipOnError: true`** — if Redis is down, rate limiting is bypassed (fail-open); this is intentional to avoid blocking all traffic on Redis failure