Phase 7: Hardening — logging, security, Docker, production readiness

Backend:
- Structured JSON logging (python-json-logger) with request ID correlation
- RequestIDMiddleware (server-generated UUID, no client trust)
- Global exception handlers: AppException, RequestValidationError, generic 500
  — all return consistent {"error": {code, message, request_id}} format
- Async rate limiting with lock + stale key eviction on auth endpoints
- Health endpoint checks DB connectivity, returns version + status
- Custom exception classes (NotFoundException, ForbiddenException, etc.)
- OpenAPI docs with tag descriptions, conditional URL (disabled in production)
- LOG_LEVEL, DOCS_ENABLED, RATE_LIMIT_* settings added

Docker:
- Backend: multi-stage build (builder + runtime), non-root user, HEALTHCHECK
- Frontend: removed dead user, HEALTHCHECK directive
- docker-compose: restart policies, healthchecks, Redis service, named volumes
  for uploads/PDFs, rate limit env vars forwarded
- Alembic migrations run only in Dockerfile CMD (removed from lifespan)

Nginx:
- server_tokens off
- CSP, Referrer-Policy, Permissions-Policy headers
- HSTS ready (commented, enable with TLS)

Config & Docs:
- .env.production.example with production-ready settings
- CLAUDE.md project conventions (structure, workflow, naming, how-to)
- .env.example updated with new variables

Review fixes applied:
- Rate limiter: async lock prevents race condition, stale key eviction
- Request ID: always server-generated (no log injection)
- Removed duplicate alembic migration from lifespan
- Removed dead app user from frontend Dockerfile
- Health check logs DB errors
- Rate limit env vars forwarded in docker-compose

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

plans/phase-7-hardening.md

@@ -0,0 +1,80 @@
+# Phase 7: Hardening — Subplan
+
+## Goal
+
+Harden for production: structured JSON logging, request tracing, global error handling, Docker security (non-root, multi-stage, health checks), rate limiting stub, security headers, OpenAPI docs, production config, and project conventions file.
+
+## Prerequisites
+
+- Phase 6 completed
+
+---
+
+## Tasks
+
+### A. Logging & Request Tracing (Tasks 1–3)
+
+- [x] **A1.** Add `python-json-logger` to pyproject.toml. Create `backend/app/core/logging.py`.
+- [x] **A2.** Create `backend/app/core/middleware.py`: RequestIDMiddleware (X-Request-ID header + contextvars).
+- [x] **A3.** Register middleware in main.py.
+
+### B. Global Error Handling (Tasks 4–5)
+
+- [x] **B4.** Create `backend/app/core/exceptions.py`: AppException + common subclasses.
+- [x] **B5.** Add global exception handlers in main.py.
+
+### C. Rate Limiting (Task 6)
+
+- [x] **C6.** Create `backend/app/core/rate_limit.py`: in-memory sliding window, add to auth endpoints. Add config settings.
+
+### D. Health Check (Task 7)
+
+- [x] **D7.** Expand `/api/v1/health` to check DB connectivity + return version.
+
+### E. Docker Hardening (Tasks 8–11)
+
+- [x] **E8.** Rewrite `backend/Dockerfile`: multi-stage, non-root user, HEALTHCHECK.
+- [x] **E9.** Update `frontend/Dockerfile`: non-root user, HEALTHCHECK.
+- [x] **E10.** Update `docker-compose.yml`: healthchecks, restart policies, Redis service.
+- [x] **E11.** Update `docker-compose.dev.yml` if needed.
+
+### F. Security Headers (Task 12)
+
+- [x] **F12.** Update `nginx/nginx.conf`: CSP, Referrer-Policy, Permissions-Policy, server_tokens off.
+
+### G. OpenAPI Docs (Task 13)
+
+- [x] **G13.** Configure OpenAPI metadata, tags, conditional docs URL in main.py.
+
+### H. Production Config (Tasks 14–15)
+
+- [x] **H14.** Create `.env.production.example`.
+- [x] **H15.** Add LOG_LEVEL, DOCS_ENABLED to config.py.
+
+### I. Project Conventions (Task 16)
+
+- [x] **I16.** Create `CLAUDE.md` with project structure, conventions, workflow docs.
+
+### J. Verification (Tasks 17–18)
+
+- [x] **J17.** Docker builds succeed, health checks pass, non-root verified.
+- [x] **J18.** Frontend builds, OpenAPI docs accessible.
+
+---
+
+## Acceptance Criteria
+
+1. Structured JSON logs with request_id correlation
+2. Consistent error response format with request_id
+3. Health endpoint checks DB + returns version
+4. Docker: non-root, multi-stage, healthchecks, restart policies
+5. Auth rate limiting (in-memory)
+6. Security headers in nginx
+7. OpenAPI docs in dev, hidden in production
+8. .env.production.example and CLAUDE.md complete
+
+---
+
+## Status
+
+**COMPLETED**