production hardening

Author: Trojan-Dev-AFK

.dockerignore

@@ -0,0 +1,16 @@
+.git
+.github
+.venv
+.pytest_cache
+.ruff_cache
+.vscode
+.idea
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.env
+.env.*
+uploads
+tests
+.claude

.env.example

@@ -1,10 +1,27 @@
 # Database
 DATABASE_URL_ASYNC=postgresql+asyncpg://username:password@localhost:5432/rag_db
 DATABASE_URL_SYNC=postgresql://username:password@localhost:5432/rag_db
+DB_POOL_SIZE=10
+DB_MAX_OVERFLOW=20
 
 # Redis
 REDIS_URL=redis://localhost:6379/0
 
+# Redis / runtime controls
+LOGIN_RATE_LIMIT_ATTEMPTS=10
+LOGIN_RATE_LIMIT_WINDOW_SECONDS=60
+CHAT_RATE_LIMIT_REQUESTS=30
+CHAT_RATE_LIMIT_WINDOW_SECONDS=60
+CHAT_IDEMPOTENCY_TTL_SECONDS=300
+TOKEN_SESSION_CACHE_TTL_SECONDS=60
+VECTOR_SEARCH_CACHE_TTL_SECONDS=300
+CHAT_HISTORY_CACHE_TTL_SECONDS=60
+DOCUMENT_METADATA_CACHE_TTL_SECONDS=60
+READINESS_REQUIRE_REDIS=true
+DEFAULT_LIST_LIMIT=50
+MAX_LIST_LIMIT=200
+MAX_UPLOAD_BYTES=26214400
+
 # Security
 SECRET_KEY=your-secret-key-here
 ALGORITHM=HS256

.github/workflows/post-merge.yml

@@ -36,6 +36,12 @@ jobs:
       - name: Vulture (Checking unused/dead production code)
         run: uv run vulture app scripts --min-confidence 70
 
+      - name: pip-audit (Checking known vulnerable dependencies)
+        run: uv run pip-audit --ignore-vuln CVE-2025-3000
+
+      - name: Bandit (Checking Python security issues)
+        run: uv run bandit -r app -q -x app/schemas
+
       - name: Thin endpoint lint (Checking endpoint-layer boundaries)
         run: uv run python scripts/lint_thin_endpoints.py
 

Dockerfile

@@ -0,0 +1,37 @@
+FROM python:3.13-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV UV_LINK_MODE=copy
+ENV UV_COMPILE_BYTECODE=1
+
+WORKDIR /app
+
+RUN apt-get update \
+	&& apt-get install -y --no-install-recommends \
+		curl \
+		libglib2.0-0 \
+		libgl1 \
+		libsm6 \
+		libxext6 \
+		libxrender1 \
+		libxcb1 \
+	&& rm -rf /var/lib/apt/lists/*
+
+RUN pip install --no-cache-dir uv
+
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev
+
+COPY alembic.ini ./
+COPY alembic ./alembic
+COPY app ./app
+COPY scripts ./scripts
+COPY docs ./docs
+
+RUN useradd -m -u 10001 appuser && chown -R appuser:appuser /app
+USER appuser
+
+EXPOSE 8000
+
+CMD ["/app/.venv/bin/uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -23,9 +23,7 @@ Cross-company access on users and documents always returns **403** — never a s
 ```bash
 uv sync --group dev       # install all dependencies
 cp .env.example .env      # configure environment
-docker-compose up -d      # start PostgreSQL + Redis
-alembic upgrade head      # apply migrations
-uvicorn app.main:app --reload
+docker-compose up -d      # start API + worker + PostgreSQL + Redis
 ```
 
 Interactive API docs: `http://localhost:8000/docs`
@@ -60,6 +58,8 @@ Full setup guide: [docs/RUNBOOK.md](docs/RUNBOOK.md)
 | `POST` | `/v1/chat/invoke` | Admin or Employee |
 | `GET` | `/v1/chat/conversations` | Admin or Employee |
 | `GET` | `/v1/chat/conversations/{conversation_id}/messages` | Admin or Employee |
+| `GET` | `/healthz` | Public (liveness) |
+| `GET` | `/readyz` | Public (readiness) |
 
 ---
 
@@ -94,10 +94,27 @@ Create a `.env` file in the project root:
 # Database
 DATABASE_URL_ASYNC=postgresql+asyncpg://agenticraguser:agenticragpwd@localhost:5432/rag_db
 DATABASE_URL_SYNC=postgresql://agenticraguser:agenticragpwd@localhost:5432/rag_db
+DB_POOL_SIZE=10
+DB_MAX_OVERFLOW=20
 
 # Redis
 REDIS_URL=redis://localhost:6379/0
 
+# Runtime controls
+LOGIN_RATE_LIMIT_ATTEMPTS=10
+LOGIN_RATE_LIMIT_WINDOW_SECONDS=60
+CHAT_RATE_LIMIT_REQUESTS=30
+CHAT_RATE_LIMIT_WINDOW_SECONDS=60
+CHAT_IDEMPOTENCY_TTL_SECONDS=300
+TOKEN_SESSION_CACHE_TTL_SECONDS=60
+VECTOR_SEARCH_CACHE_TTL_SECONDS=300
+CHAT_HISTORY_CACHE_TTL_SECONDS=60
+DOCUMENT_METADATA_CACHE_TTL_SECONDS=60
+READINESS_REQUIRE_REDIS=true
+DEFAULT_LIST_LIMIT=50
+MAX_LIST_LIMIT=200
+MAX_UPLOAD_BYTES=26214400
+
 # Security
 SECRET_KEY=your-secret-key-here
 ALGORITHM=HS256
@@ -125,6 +142,16 @@ LOCAL_UPLOAD_DIR=uploads
 # S3_BUCKET_NAME=agentic-rag-api
 ```
 
+## Container deployment
+
+```bash
+# Build
+docker build -t agentic-rag-api:latest .
+
+# Run API container (expects DB/Redis reachable from this network)
+docker run --rm -p 8000:8000 --env-file .env agentic-rag-api:latest
+```
+
 Full variable reference: [docs/RUNBOOK.md#environment-variables-reference](docs/RUNBOOK.md#environment-variables-reference)
 
 ---
@@ -137,6 +164,7 @@ Full variable reference: [docs/RUNBOOK.md#environment-variables-reference](docs/
 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Component diagram, request lifecycle, singleton model loading, storage backend design, RBAC model |
 | [docs/ENDPOINT_ACCESS_MATRIX.md](docs/ENDPOINT_ACCESS_MATRIX.md) | Quick role/access lookup for all endpoints |
 | [docs/RUNBOOK.md](docs/RUNBOOK.md) | Full setup, service startup/shutdown, migrations, monitoring, common ops tasks, S3 setup, backup/restore |
+| [docs/PRODUCTION_DEPLOYMENT.md](docs/PRODUCTION_DEPLOYMENT.md) | Step-by-step production deployment sequence with Docker, migrations, API/worker startup, and S3 linking |
 | [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | Code standards, docstring style, singleton pattern, adding endpoints, migrations, logging conventions |
 | [docs/CHANGELOG.md](docs/CHANGELOG.md) | Historical record of architecture, ingestion, RBAC, CI, and chat-history milestones |
 

app/agent/tools/vector_search.py

@@ -1,6 +1,7 @@
 """LangGraph tool: semantic search over document chunks using pgvector cosine distance."""
 
 from contextvars import ContextVar, Token
+from hashlib import sha256
 
 from langchain_core.tools import tool
 from langchain_huggingface import HuggingFaceEmbeddings
@@ -9,6 +10,7 @@
 
 from app.core.config import settings
 from app.core.logger import get_logger
+from app.core.runtime_controls import cache_get_text, cache_set_text
 from app.db.models import ChunkType, Document, DocumentChunk
 from app.db.session import AsyncSessionLocal
 
@@ -94,6 +96,13 @@ async def search_documents(query: str) -> str:
         )
     query_counts[normalized_query] = repeat_count + 1
 
+    query_hash = sha256(normalized_query.encode("utf-8")).hexdigest()
+    cache_key = f"cache:vector:{company_id}:{query_hash}"
+    cached_context = await cache_get_text(key=cache_key)
+    if cached_context:
+        logger.info("Vector search cache hit", extra={"company_id": company_id})
+        return cached_context
+
     try:
         query_vector = _get_embeddings_model().embed_query(query)
     except Exception as exc:
@@ -128,4 +137,10 @@ async def search_documents(query: str) -> str:
         )
         for text, chunk_type in chunks
     ]
-    return "\n\n---\n\n".join(formatted_chunks)
+    response_context = "\n\n---\n\n".join(formatted_chunks)
+    await cache_set_text(
+        key=cache_key,
+        value=response_context,
+        ttl_seconds=settings.VECTOR_SEARCH_CACHE_TTL_SECONDS,
+    )
+    return response_context

app/api/dependencies.py

@@ -21,6 +21,7 @@
 
 from app.core.config import settings
 from app.core.logger import get_logger
+from app.core.runtime_controls import token_session_cache_get, token_session_cache_set
 from app.db.models import TokenSession, User, UserRole
 from app.db.session import get_db
 
@@ -53,6 +54,10 @@ async def get_current_user(token: str = Depends(oauth2_scheme), db: AsyncSession
         logger.warning("JWT references unknown user", extra={"username": username})
         raise credentials_exception
 
+    cached_user_id = await token_session_cache_get(jti=jti)
+    if cached_user_id == user.id:
+        return user
+
     session_result = await db.execute(
         select(TokenSession).filter(TokenSession.jti == jti, TokenSession.user_id == user.id)
     )
@@ -71,6 +76,10 @@ async def get_current_user(token: str = Depends(oauth2_scheme), db: AsyncSession
         logger.warning("Attempt to use expired token", extra={"user_id": user.id, "jti": jti})
         raise credentials_exception
 
+    remaining_seconds = int((token_session.expires_at - datetime.now(UTC)).total_seconds())
+    ttl_seconds = max(1, min(settings.TOKEN_SESSION_CACHE_TTL_SECONDS, remaining_seconds))
+    await token_session_cache_set(jti=jti, user_id=user.id, ttl_seconds=ttl_seconds)
+
     return user
 
 

app/api/v1/endpoints/auth.py

@@ -17,7 +17,10 @@
 @router.post(
     "/login",
     response_model=TokenResponse,
-    responses={401: {"description": "Invalid username or password."}},
+    responses={
+        401: {"description": "Invalid username or password."},
+        429: {"description": "Too many login attempts."},
+    },
 )
 async def login_for_access_token(
     request: Request,

app/api/v1/endpoints/chat.py

@@ -1,6 +1,6 @@
 """Chat endpoint — submits a query to the LangGraph RAG agent."""
 
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, Header, Query
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.api.dependencies import require_company_user
@@ -17,11 +17,13 @@
     response_model=ChatResponse,
     responses={
         403: {"description": "Forbidden — `super_admin` accounts cannot use chat."},
+        429: {"description": "Too many chat requests."},
         502: {"description": "Agent service unavailable — LLM or tool call failed."},
     },
 )
 async def invoke_agent(
     request: ChatRequest,
+    idempotency_key: str | None = Header(default=None, alias="X-Idempotency-Key"),
     db: AsyncSession = Depends(get_db),
     current_user: User = Depends(require_company_user),
 ):
@@ -37,6 +39,7 @@ async def invoke_agent(
     response_text, conversation_id = await chat_service.invoke_agent(
         query=request.query,
         conversation_id=request.conversation_id,
+        idempotency_key=idempotency_key,
         db=db,
         current_user=current_user,
     )
@@ -45,22 +48,38 @@ async def invoke_agent(
 
 @router.get("/conversations", response_model=list[ChatConversationResponse])
 async def list_conversations(
+    limit: int | None = Query(default=None, ge=1, le=500),
+    offset: int | None = Query(default=None, ge=0),
     db: AsyncSession = Depends(get_db),
     current_user: User = Depends(require_company_user),
 ):
     """List persisted chat conversations for the current authenticated user."""
-    return await chat_service.list_conversations(db=db, current_user=current_user)
+    service_kwargs: dict = {"db": db, "current_user": current_user}
+    if limit is not None:
+        service_kwargs["limit"] = limit
+    if offset is not None:
+        service_kwargs["offset"] = offset
+    return await chat_service.list_conversations(**service_kwargs)
 
 
 @router.get("/conversations/{conversation_id}/messages", response_model=list[ChatMessageResponse])
 async def get_conversation_messages(
     conversation_id: str,
+    limit: int | None = Query(default=None, ge=1, le=500),
+    offset: int | None = Query(default=None, ge=0),
     db: AsyncSession = Depends(get_db),
     current_user: User = Depends(require_company_user),
 ):
     """Get persisted messages for one conversation owned by the current user."""
+    service_kwargs: dict = {
+        "conversation_id": conversation_id,
+        "db": db,
+        "current_user": current_user,
+    }
+    if limit is not None:
+        service_kwargs["limit"] = limit
+    if offset is not None:
+        service_kwargs["offset"] = offset
     return await chat_service.get_conversation_messages(
-        conversation_id=conversation_id,
-        db=db,
-        current_user=current_user,
+        **service_kwargs,
     )

app/api/v1/endpoints/companies.py

@@ -1,6 +1,6 @@
 """Company management endpoints — Super Admin only."""
 
-from fastapi import APIRouter, Depends, status
+from fastapi import APIRouter, Depends, Query, status
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.api.dependencies import require_super_admin
@@ -28,11 +28,18 @@ async def create_company(
 
 @router.get("/", response_model=list[CompanyResponse])
 async def list_companies(
+    limit: int | None = Query(default=None, ge=1, le=500),
+    offset: int | None = Query(default=None, ge=0),
     db: AsyncSession = Depends(get_db),
     current_user: User = Depends(require_super_admin),
 ):
     """Return all companies ordered by name (super admin only)."""
-    return await companies_service.list_companies(db=db, current_user=current_user)
+    service_kwargs: dict = {"db": db, "current_user": current_user}
+    if limit is not None:
+        service_kwargs["limit"] = limit
+    if offset is not None:
+        service_kwargs["offset"] = offset
+    return await companies_service.list_companies(**service_kwargs)
 
 
 @router.get("/{company_id}", response_model=CompanyResponse)