Production hardening: JWT blacklist, TOTP, Pydantic schemas, Prometheus, SSRF fix, CSP, Redis auth, Celery backup — 35 items across P0-P5

.cursorrules

@@ -0,0 +1,698 @@
+# ═══════════════════════════════════════════════════════════════════════════════
+# AUTHORBOT RAG — PRODUCTION RULES ($500K BUDGET, ENTERPRISE SaaS)
+# ═══════════════════════════════════════════════════════════════════════════════
+#
+# READ THIS FILE BEFORE EVERY SESSION. NO EXCEPTIONS.
+#
+# These rules are derived from a line-by-line audit of the entire codebase.
+# Every rule exists because we found a gap, a vulnerability, or an inconsistency
+# that WILL cause problems at production scale.
+#
+# Format: Each rule has a WHY, WHERE, and ENFORCEMENT section.
+# Status: ✅ = Implemented, ❌ = NOT YET (must fix), ⚠️ = Partial
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §1. AUTHENTICATION & AUTHORIZATION
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-001: Passwords MUST be hashed with bcrypt ≥12 rounds.
+#   WHY: Lower rounds are brute-forceable with modern GPUs.
+#   WHERE: app/services/auth_service.py → _hash_password()
+#   STATUS: ✅ Implemented (rounds=12)
+
+# R-002: Failed login MUST trigger account lockout (5 attempts → 15-min lock).
+#   WHY: Prevents credential stuffing attacks.
+#   WHERE: app/services/auth_service.py → login()
+#   STATUS: ✅ Implemented
+
+# R-003: Non-existent email MUST take constant time to respond.
+#   WHY: Timing attacks can enumerate valid emails.
+#   WHERE: app/services/auth_service.py:98-99 (dummy bcrypt comparison)
+#   STATUS: ✅ Implemented
+
+# R-004: JWT refresh MUST invalidate the old token (Redis blacklist by jti).
+#   WHY: Stolen tokens remain valid until natural expiry without blacklisting.
+#   WHERE: app/services/auth_service.py → refresh_tokens()
+#   STATUS: ❌ NOT IMPLEMENTED — old token still valid after refresh
+
+# R-005: Logout MUST add current JWT to Redis blacklist (TTL = remaining lifetime).
+#   WHY: Cookie deletion is client-side only; server still accepts the token.
+#   WHERE: app/api/schemas_router.py:78-81
+#   STATUS: ❌ NOT IMPLEMENTED — only deletes cookie
+
+# R-006: Refresh token MUST use HttpOnly + Secure + SameSite=Lax.
+#   WHY: Prevents XSS from stealing refresh tokens.
+#   WHERE: app/api/schemas_router.py:26-35
+#   STATUS: ✅ Implemented
+
+# R-007: SuperAdmin routes MUST require JWT + TOTP on EVERY request.
+#   WHY: Single-factor auth on God-mode access = catastrophic if JWT stolen.
+#   WHERE: app/dependencies.py → get_current_superadmin()
+#   STATUS: ❌ NOT IMPLEMENTED — only checks role, TOTP module exists but unused
+
+# R-008: Registration MUST validate email format (RFC 5322 regex or Pydantic EmailStr).
+#   WHY: Invalid emails break notification system and create ghost accounts.
+#   WHERE: app/services/auth_service.py → register()
+#   STATUS: ❌ NOT IMPLEMENTED — only lower().strip()
+
+# R-009: Registration MUST enforce password complexity (≥8 chars, mixed case + digit).
+#   WHY: Weak passwords on admin accounts = easy takeover.
+#   WHERE: app/services/auth_service.py → register()
+#   STATUS: ❌ NOT IMPLEMENTED — no minimum length or complexity check
+
+# R-010: Password change MUST validate via Pydantic schema (not raw dict).
+#   WHY: Raw dicts skip type coercion, field validation, and OpenAPI docs.
+#   WHERE: app/admin/router.py:461-487
+#   STATUS: ❌ NOT IMPLEMENTED — uses body: dict
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §2. SUBSCRIPTION & TOKEN SECURITY
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-011: Subscription token HMAC MUST use constant-time comparison.
+#   WHY: Non-constant comparison leaks signature bytes via timing side-channel.
+#   WHERE: app/core/access/token_crypto.py:179
+#   STATUS: ✅ hmac.compare_digest()
+
+# R-012: Raw subscription tokens MUST never be stored — only SHA-256 hash.
+#   WHY: DB breach exposes all tokens if stored in plaintext.
+#   WHERE: app/core/access/token_crypto.py:199-210
+#   STATUS: ✅ Implemented
+
+# R-013: Token validation MUST check all 5 layers (HMAC → Expiry → Redis → DB → Budget).
+#   WHY: Skipping any layer creates a bypass.
+#   WHERE: app/core/access/subscription.py:34-111
+#   STATUS: ✅ Implemented
+
+# R-014: tokens_used MUST be incremented atomically on every chat turn.
+#   WHY: Read-modify-write on ORM object loses increments under concurrency.
+#   WHERE: app/services/token_budget.py:89
+#   STATUS: ❌ NOT ATOMIC — uses Python addition instead of SQL atomic update
+#   FIX: Use `update(ClientAccess).values(tokens_used=ClientAccess.tokens_used + N)`
+
+# R-015: budget_exhausted flag MUST be set at 100% usage.
+#   WHY: Without it, exhausted authors continue using API at our cost.
+#   WHERE: app/services/token_budget.py:92-93
+#   STATUS: ✅ Redis flag set
+
+# R-016: BudgetExhaustedError MUST return HTTP 200 (not 403) with friendly message.
+#   WHY: Visitors should see "Taking a short break" not "Budget exhausted" error.
+#   WHERE: app/dependencies.py:210-211 overrides the global handler in main.py
+#   STATUS: ❌ BROKEN — dependency catches and re-raises as HTTPException(403)
+#   FIX: Let BudgetExhaustedError propagate uncaught to the global handler.
+
+# R-017: Token budget formula MUST always be: total = token_budget + bonus_tokens.
+#   WHY: Inconsistent formula = different numbers on admin vs superadmin vs embed.
+#   WHERE: app/services/token_budget.py → total_budget()
+#   STATUS: ✅ Centralized in token_budget.py
+
+# R-018: Revocation MUST propagate to Redis blacklist immediately (O(1) check).
+#   WHY: DB-only revocation has latency; widget keeps working for cached sessions.
+#   WHERE: app/services/superadmin_service.py:308-312
+#   STATUS: ✅ Implemented
+
+# R-019: chatbot_is_active=false MUST block all chat requests.
+#   WHY: Suspended authors must not serve visitors.
+#   WHERE: app/core/access/subscription.py:108-109
+#   STATUS: ✅ Checked in validation chain
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §3. RATE LIMITING & DDoS PROTECTION
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-020: Chat endpoint rate limit: 60 req/min per IP.
+#   WHERE: app/middleware/rate_limit_middleware.py:21
+#   STATUS: ✅ Implemented
+
+# R-021: Auth endpoint rate limit: 10 req/min per IP.
+#   WHERE: app/middleware/rate_limit_middleware.py:22
+#   STATUS: ✅ Implemented
+
+# R-022: Rate limiter MUST fail-open (no Redis = allow traffic, not crash).
+#   WHERE: app/middleware/rate_limit_middleware.py:61-62
+#   STATUS: ✅ Implemented
+
+# R-023: SSE endpoints MUST have a max connection timeout (5 minutes).
+#   WHY: Unbounded SSE = connection exhaustion attack vector.
+#   WHERE: app/api/chat.py:252-274, app/api/ingest.py:90-116
+#   STATUS: ❌ NOT IMPLEMENTED — runs forever until client disconnects
+#   FIX: Wrap SSE loop in asyncio.timeout(300). Send heartbeat pings every 30s.
+
+# R-024: File upload MUST reject oversized files BEFORE reading into memory.
+#   WHY: A 500MB upload = 500MB RAM consumption before any validation.
+#   WHERE: app/api/ingest.py:43
+#   STATUS: ❌ NOT IMPLEMENTED — file.read() loads everything first
+#   FIX: Use chunked reads or set max_upload_size on Starlette.
+
+# R-025: X-Forwarded-For MUST NOT be blindly trusted (use rightmost trusted proxy).
+#   WHY: Attackers spoof X-Forwarded-For to bypass IP rate limits.
+#   WHERE: app/middleware/rate_limit_middleware.py:76-82
+#   STATUS: ⚠️ PARTIAL — takes first value, which is user-controllable
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §4. INPUT VALIDATION & SANITIZATION
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-026: All chat input MUST be sanitized (control chars, zero-width, delimiters).
+#   WHERE: app/services/guardrails.py → sanitize_input()
+#   STATUS: ✅ Implemented
+
+# R-027: Chat input hard cap: 2000 characters. No exceptions.
+#   WHERE: app/services/guardrails.py
+#   STATUS: ✅ Implemented
+
+# R-028: Jailbreak detection: 30+ regex patterns, ≥2 signals = auto-block.
+#   WHERE: app/services/guardrails.py → check_boundary()
+#   STATUS: ✅ Implemented
+
+# R-029: ALL admin API endpoints MUST use Pydantic BaseModel schemas (NOT raw dict).
+#   WHY: Raw dicts skip validation, type coercion, and OpenAPI documentation.
+#   WHERE: 16+ endpoints across admin/router.py, chat.py, superadmin/router.py
+#   STATUS: ❌ NOT IMPLEMENTED — most admin endpoints use body: dict
+#   AFFECTED: password change, widget config, profile, personality, notifications,
+#     smart links, Q&A, annotate, flag, track-click, feedback, rate, announce, grant
+
+# R-030: All path parameter IDs MUST be validated as UUID format.
+#   WHY: Garbage IDs cause unhandled DB errors instead of clean 400s.
+#   WHERE: All routers — book_id, session_id, message_id, qa_id, grant_id, author_id
+#   STATUS: ❌ NOT IMPLEMENTED — all IDs are plain str
+
+# R-031: URL inputs (smart links) MUST validate scheme (https preferred) and format.
+#   WHY: Invalid URLs break widget buttons; internal URLs enable SSRF.
+#   WHERE: app/admin/router.py:730-733
+#   STATUS: ❌ NOT IMPLEMENTED — only length check, no format/scheme validation
+
+# R-032: CSV import MUST sanitize HTML/script content in Q&A answers.
+#   WHY: Q&A answers are rendered in the widget — XSS vector.
+#   WHERE: app/admin/router.py:1022-1082
+#   STATUS: ⚠️ PARTIAL — length-limited but no HTML stripping
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §5. FILE UPLOAD SECURITY
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-033: MIME type MUST be verified by magic bytes, NEVER by file extension alone.
+#   WHERE: app/services/file_validator.py via file_utils.validate_upload
+#   STATUS: ✅ Implemented
+
+# R-034: Cover images MUST strip EXIF metadata (privacy: GPS coords, camera serial).
+#   WHERE: app/admin/router.py:302 — img.convert('RGB') strips EXIF
+#   STATUS: ✅ Implemented
+
+# R-035: Upload paths MUST use server-generated names (UUID), NEVER user filenames.
+#   WHY: User filenames enable directory traversal (../../etc/passwd).
+#   WHERE: app/api/ingest.py:60 uses book.id (UUID)
+#   STATUS: ✅ Implemented
+
+# R-036: Temp files MUST be cleaned up on both success AND failure paths.
+#   WHERE: app/api/ingest.py:175-181 (finally block)
+#   STATUS: ✅ Implemented
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §6. DATA ISOLATION & TENANT SECURITY
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-037: Every DB query MUST be scoped by author_id. No cross-tenant data access.
+#   WHERE: All repositories
+#   STATUS: ✅ Implemented
+
+# R-038: Admin slug in URL MUST match authenticated user's ID.
+#   WHERE: app/dependencies.py:168-175 → get_current_author_scoped()
+#   STATUS: ✅ Implemented
+
+# R-039: ChromaDB collections MUST be namespaced by author_id prefix.
+#   WHERE: app/services/vector_store.py:133-148
+#   STATUS: ✅ Implemented
+
+# R-040: Message annotation/flag endpoints MUST verify session ownership chain.
+#   WHY: Without it, any author can annotate any other author's messages (IDOR).
+#   WHERE: app/admin/router.py:858-928
+#   STATUS: ❌ NOT IMPLEMENTED — queries by message_id+session_id but NEVER checks
+#     that ChatSession.author_id == current_user.id
+#   FIX: Add JOIN to ChatSession and filter by author_id.
+
+# R-041: Visitor fingerprints MUST be one-way hashed (SHA-256), never raw PII.
+#   WHERE: app/api/chat.py:34-41
+#   STATUS: ✅ Implemented
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §7. API SECURITY & ERROR HANDLING
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-042: Security headers MUST be on every HTTP response.
+#   Required: X-Content-Type-Options, X-Frame-Options, X-XSS-Protection,
+#     Referrer-Policy, Permissions-Policy, HSTS (production only).
+#   WHERE: app/middleware/security_headers.py
+#   STATUS: ✅ Implemented
+
+# R-043: Content-Security-Policy header MUST be set.
+#   WHY: CSP is the primary defense against XSS in modern browsers.
+#   WHERE: app/middleware/security_headers.py
+#   STATUS: ❌ NOT IMPLEMENTED
+
+# R-044: Error responses MUST NOT contain internal exception messages, SQL, or paths.
+#   WHY: Information disclosure helps attackers map the system.
+#   WHERE: app/superadmin/router.py:44-51 — _err() includes str(e)[:200]
+#   STATUS: ❌ LEAKS DETAILS — returns exception text to client
+
+# R-045: No public/unauthenticated diagnostic endpoints on admin routers.
+#   WHERE: app/superadmin/router.py:76-79 — GET /api/super/diag has NO auth
+#   STATUS: ❌ PUBLIC ENDPOINT on SuperAdmin router
+
+# R-046: No duplicate route definitions (causes unpredictable routing).
+#   WHERE: app/api/chat.py — rate_session defined TWICE (L219 and L346)
+#   STATUS: ❌ DUPLICATE — first definition silently ignored
+
+# R-047: CORS MUST NOT use wildcard (*) origins in production.
+#   WHERE: app/main.py → CORSMiddleware config
+#   STATUS: ⚠️ NEEDS VERIFICATION
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §8. DATABASE RULES
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-048: All schema changes MUST use Alembic migrations. No manual DDL.
+#   WHY: Manual schema changes risk data loss and cannot be rolled back.
+#   WHERE: Project root — NO alembic.ini or alembic/ directory exists
+#   STATUS: ❌ NOT CONFIGURED
+
+# R-049: All queries MUST use parameterized statements (ORM or bound params).
+#   WHERE: All repositories use SQLAlchemy ORM
+#   STATUS: ✅ Implemented
+
+# R-050: DB transactions MUST auto-rollback on exception.
+#   WHERE: app/dependencies.py:57-65
+#   STATUS: ✅ Implemented
+
+# R-051: All datetimes MUST use timezone-aware UTC (datetime.now(timezone.utc)).
+#   WHY: datetime.utcnow() is deprecated and returns naive datetimes.
+#   WHERE: Mixed — some files use now(timezone.utc), others use utcnow()
+#   STATUS: ❌ INCONSISTENT — 3+ files still use deprecated utcnow()
+
+# R-052: Concurrent writes MUST be atomic (SQL UPDATE, not Python read-modify-write).
+#   WHY: ORM-level addition loses increments under concurrent requests.
+#   WHERE: app/services/token_budget.py:89
+#   STATUS: ❌ NOT ATOMIC
+
+# R-053: High-traffic columns MUST have database indexes.
+#   Required indexes: author_id, session_id, created_at, timestamp
+#   WHERE: app/models/ — no explicit index definitions visible
+#   STATUS: ❌ NOT IMPLEMENTED
+
+# R-054: Soft delete SHOULD be preferred for auditable records.
+#   WHERE: Books and authors use hard delete; only ClientAccess uses soft delete
+#   STATUS: ⚠️ PARTIAL
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §9. REDIS INFRASTRUCTURE
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-055: Redis MUST have authentication (--requirepass) in production.
+#   WHERE: Dockerfile — embedded Redis starts without password
+#   STATUS: ❌ NOT CONFIGURED
+
+# R-056: All Redis keys MUST have TTL — no orphan keys.
+#   WHERE: app/services/token_budget.py:82, rate_limit_middleware.py:54
+#   STATUS: ✅ Implemented
+
+# R-057: Redis connection MUST be pooled.
+#   WHERE: app/dependencies.py:94-104
+#   STATUS: ✅ Implemented
+
+# R-058: Redis failure MUST NOT crash the application (graceful degradation).
+#   WHERE: All Redis operations wrapped in try/except
+#   STATUS: ✅ Implemented
+
+# R-059: Redis persistence MUST be explicitly configured (AOF preferred for durability).
+#   WHERE: Dockerfile
+#   STATUS: ⚠️ Uses default RDB — should configure AOF for session/token data
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §10. RAG PIPELINE INTEGRITY
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-060: Every chat message MUST pass through ALL 12 pipeline steps. No bypass.
+#   WHERE: app/services/rag_pipeline.py
+#   STATUS: ✅ Sequential execution
+
+# R-061: Guardrails MUST run BEFORE any LLM call (input sanitize + boundary check).
+#   WHERE: Pipeline steps 0-1 run before step 2
+#   STATUS: ✅ Implemented
+
+# R-062: Output safety MUST run on EVERY generated response (no AI identity leaks).
+#   WHERE: app/services/guardrails.py → is_response_safe()
+#   STATUS: ✅ Implemented
+
+# R-063: Faithfulness NLI check MUST trigger one regeneration, then safe fallback.
+#   WHERE: app/services/rag_pipeline.py
+#   STATUS: ✅ Implemented
+
+# R-064: Context window MUST NOT exceed RAG_MAX_CONTEXT_TOKENS (4096).
+#   WHERE: app/services/context_builder.py
+#   STATUS: ✅ Hard limit enforced
+
+# R-065: response_style MUST be injected into the LLM system prompt.
+#   WHY: Admin personality settings currently have ZERO effect on output.
+#   WHERE: app/services/rag_pipeline.py + app/services/prompter.py
+#   STATUS: ❌ NOT IMPLEMENTED — style is saved to DB but never reaches the prompt
+
+# R-066: All prompts MUST live in app/services/prompter.py. No inline prompts.
+#   WHERE: All pipeline services
+#   STATUS: ✅ Implemented
+
+# R-067: LLM errors MUST return warm human fallback, never a crash or error code.
+#   WHERE: app/services/rag_pipeline.py — try/except at every step
+#   STATUS: ✅ Implemented
+
+# R-068: Responses MUST NOT contain markdown (bold, bullets, headers, code blocks).
+#   WHERE: System prompt + output guardrails
+#   STATUS: ✅ Enforced
+
+# R-069: No spoilers — never summarize full plot, retell story, or reveal endings.
+#   WHERE: System prompt instructions
+#   STATUS: ✅ Enforced in prompt
+
+# R-070: Max response length: ~75 words, 2 paragraphs, 380 chars.
+#   WHERE: System prompt + formatter
+#   STATUS: ✅ Enforced
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §11. ADMIN PANEL CONSISTENCY
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-071: Token usage display MUST include bonus_tokens in total budget.
+#   WHERE: app/admin/router.py:753-765 via usage_summary_or_empty()
+#   STATUS: ✅ Implemented
+
+# R-072: Embed token card MUST show same remaining count as token usage page.
+#   WHERE: Both use tokens_remaining() from token_budget.py
+#   STATUS: ✅ Implemented
+
+# R-073: Book deletion MUST clean up ChromaDB collection.
+#   WHERE: app/admin/router.py:243-244
+#   STATUS: ✅ Implemented
+
+# R-074: Smart Links MUST sync both books.buy_url AND links.purchase_url.
+#   WHERE: app/admin/router.py:735-747
+#   STATUS: ✅ Implemented
+
+# R-075: Export endpoints MUST have row limits (prevent OOM on large datasets).
+#   WHERE: app/admin/router.py:1219 — .limit(50000)
+#   STATUS: ✅ Implemented
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §12. SUPERADMIN PANEL
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-076: Every SuperAdmin mutation MUST write to the audit log. No exceptions.
+#   WHERE: app/services/superadmin_service.py — all 7 mutations have _audit.log()
+#   STATUS: ✅ Implemented
+
+# R-077: Audit log MUST be append-only — no UPDATE or DELETE endpoints.
+#   WHERE: app/superadmin/router.py:316-344 — only GET
+#   STATUS: ✅ Implemented
+
+# R-078: Author deletion MUST revoke all active tokens (Redis + DB).
+#   WHERE: app/services/superadmin_service.py:155-164
+#   STATUS: ✅ Implemented
+
+# R-079: Self-deletion and SuperAdmin deletion MUST be prevented.
+#   WHERE: app/services/superadmin_service.py:148-151
+#   STATUS: ✅ Implemented
+
+# R-080: Backup MUST NOT run synchronously on the API event loop.
+#   WHY: Blocks all concurrent requests during backup.
+#   WHERE: app/superadmin/router.py:436-444 — run_backup() is synchronous
+#   STATUS: ❌ RUNS SYNCHRONOUSLY
+#   FIX: Dispatch to Celery task or use asyncio.to_thread().
+
+# R-081: Grant-by-email MUST validate plan name against known list.
+#   WHERE: app/superadmin/router.py:408-413
+#   STATUS: ⚠️ PARTIAL — plan_map exists but no error for unknown plans
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §13. BACKGROUND TASKS & CELERY
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-082: Document ingestion MUST use Celery (not asyncio.create_task on API process).
+#   WHY: asyncio.create_task = lost on restart, no retry, blocks API workers.
+#   WHERE: app/api/ingest.py:76-85
+#   STATUS: ❌ NOT IMPLEMENTED — uses asyncio.create_task() despite Celery task existing
+#   FIX: Replace with process_document.delay(doc_id, author_id, book_id, path, ext)
+
+# R-083: Celery tasks MUST use acks_late + max_retries for crash resilience.
+#   WHERE: app/tasks/celery_app.py:35, app/tasks/ingestion_task.py:22-28
+#   STATUS: ✅ Configured
+
+# R-084: SSE status broadcasts MUST use consistent Redis channel naming.
+#   WHERE: ingestion_task.py uses "ingestion:{author_id}"
+#     but ingest.py uses "ingestion:{author_id}:{book_id}"
+#   STATUS: ❌ INCONSISTENT — different channel patterns between Celery and asyncio paths
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §14. CI/CD & TESTING
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-085: CI MUST fail on test failures. `|| true` is FORBIDDEN.
+#   WHY: Broken code deploys to production automatically.
+#   WHERE: .github/workflows/ci.yml:57
+#   STATUS: ❌ USES `|| true` — tests NEVER block deployment
+
+# R-086: Test coverage MUST meet minimum threshold (≥80%).
+#   WHERE: ci.yml:57 — --cov-fail-under is NOT set
+#   STATUS: ❌ NOT ENFORCED
+
+# R-087: CI MUST include Redis and PostgreSQL services for integration tests.
+#   WHERE: ci.yml:51-55 — references redis://localhost:6379 but no Redis service
+#   STATUS: ❌ REDIS NOT AVAILABLE IN CI
+
+# R-088: BDD specs MUST run in CI (behave tests/bdd/features/).
+#   WHERE: ci.yml — no behave step
+#   STATUS: ❌ NOT CONFIGURED
+
+# R-089: Deployment MUST be gated on test success (needs: test meaningful only if tests run).
+#   WHERE: ci.yml:69-70 — needs: test is meaningless with || true
+#   STATUS: ❌ DEPLOY IS UNGATED
+
+# R-090: Every new function → at least 1 unit test.
+# R-091: Every new API endpoint → at least 1 integration test.
+# R-092: Every new feature → BDD scenario in .agent/BDD_SPECS.md FIRST.
+# R-093: Mock ALL external services in unit tests (OpenAI, DB, Redis, email).
+# R-094: Use pytest fixtures for shared setup — no repeated setup code.
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §15. OBSERVABILITY & MONITORING
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-095: Structured logging (structlog) MUST be used everywhere. No print().
+#   WHERE: All services
+#   STATUS: ✅ Implemented
+
+# R-096: Request/response logging middleware MUST be active.
+#   WHERE: app/middleware/logging_middleware.py
+#   STATUS: ✅ Implemented
+
+# R-097: Token values, passwords, API keys MUST never appear in logs.
+#   WHERE: app/core/access/token_crypto.py:5-6 (rule documented)
+#   STATUS: ✅ Implemented
+
+# R-098: Health endpoint MUST check DB + Redis + ChromaDB.
+#   WHERE: app/dependencies.py:216-249
+#   STATUS: ✅ Implemented
+
+# R-099: Prometheus /metrics endpoint MUST be configured.
+#   STATUS: ❌ NOT IMPLEMENTED
+
+# R-100: Error alerting (Sentry or equivalent) MUST be configured.
+#   STATUS: ❌ NOT IMPLEMENTED
+
+# R-101: Audit log MUST capture actor IP address (for forensics).
+#   STATUS: ❌ NOT IMPLEMENTED — only captures actor_email
+
+# R-102: Per-step pipeline latency MUST be tracked (not just total response_ms).
+#   STATUS: ❌ NOT IMPLEMENTED
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §16. DEPLOYMENT & INFRASTRUCTURE
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-103: Secrets MUST NOT be in version control.
+#   WHERE: .env in .gitignore
+#   STATUS: ✅ Implemented
+
+# R-104: Docker image MUST use multi-stage build (minimal production image).
+#   WHERE: Dockerfile
+#   STATUS: ✅ Implemented
+
+# R-105: Container SHOULD run as non-root user.
+#   WHERE: Dockerfile
+#   STATUS: ❌ RUNS AS ROOT
+
+# R-106: Database backups MUST be automated (Celery Beat schedule).
+#   WHERE: No backup task in Celery Beat schedule
+#   STATUS: ❌ NOT SCHEDULED
+
+# R-107: Health check MUST have startup grace period.
+#   WHERE: Dockerfile — 180s start period
+#   STATUS: ✅ Implemented
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §17. CODE STRUCTURE CONVENTIONS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-108: All configuration from app/config.py (pydantic BaseSettings). Never hardcode.
+# R-109: All DI via FastAPI Depends() in app/dependencies.py.
+# R-110: All DB access via repository pattern (app/repositories/).
+# R-111: Business logic in app/services/ — never in route handlers.
+# R-112: Background work in Celery tasks (app/tasks/) — never asyncio.create_task for long work.
+# R-113: Custom exceptions in app/exceptions/ — never raise generic Exception.
+# R-114: Every module MUST have a module-level docstring.
+# R-115: Every function MUST have type-annotated signature + docstring.
+# R-116: No function longer than 40 lines — refactor into named helpers.
+# R-117: Update FILE_MAP.md when adding or removing any file.
+# R-118: Update BDD_SPECS.md before implementing any new user-facing feature.
+# R-119: Read .agent/RULES.md and .agent/FILE_MAP.md before every coding session.
+# R-120: All destructive UI actions require confirmation dialog with typed confirmation.
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §18. FRONTEND & WIDGET SECURITY
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-121: Widget escHtml() MUST escape ALL 5 HTML entities (&, <, >, ", ').
+#   WHY: Incomplete escaping enables XSS in bot responses rendered as innerHTML.
+#   WHERE: static/widget.js:483-484
+#   STATUS: ✅ Implemented — all 5 entities covered
+
+# R-122: Widget link buttons MUST always use target="_blank" rel="noopener".
+#   WHY: Without noopener, linked pages can hijack the parent window (reverse tabnabbing).
+#   WHERE: static/widget.js:371
+#   STATUS: ✅ Implemented
+
+# R-123: Widget MUST NOT expose subscription token in DOM or global JS scope.
+#   WHY: Any page script can steal the token from window variables or DOM attributes.
+#   WHERE: static/widget.js:22-38 — token stored in closure variable (not window)
+#   STATUS: ✅ Token stays in IIFE closure
+
+# R-124: Admin SPA MUST redirect to /login on 401 response (not show broken UI).
+#   WHY: Stale JWTs leave admin in a broken state with no clear recovery.
+#   WHERE: static/auth-client.js
+#   STATUS: ⚠️ PARTIAL — auth-client.js exists but redirect behavior varies by page
+
+# R-125: /widget endpoint MUST NOT serve with Access-Control-Allow-Origin: *.
+#   WHY: Exposes widget test page to cross-origin embedding by any domain.
+#   WHERE: app/main.py:294 — explicitly adds "*" CORS header on /widget response
+#   STATUS: ❌ WILDCARD CORS — anyone can embed the test page
+
+# R-126: /covers static mount MUST disable directory listing.
+#   WHY: Attackers can enumerate all cover images and map author IDs from filenames.
+#   WHERE: app/main.py:265-266 — StaticFiles(directory=covers_dir)
+#   STATUS: ⚠️ StaticFiles does NOT list by default, but doesn't 404 on /covers/ root
+
+# R-127: Widget size budget: widget.js MUST stay under 25KB minified.
+#   WHY: Widget loads on third-party author websites; large JS hurts page speed.
+#   WHERE: static/widget.js — currently 19.7KB unminified (523 lines)
+#   STATUS: ⚠️ Under budget unminified, but no minification or CDN configured
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §19. CELERY TASKS — DATA QUALITY
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-128: Weekly digest email MUST populate actual stats (not hardcoded 0).
+#   WHY: Emails with "0 sessions, 0% tokens" destroy author trust.
+#   WHERE: app/tasks/email_task.py:39-46 — chat_count=0, token_pct=0, top_country="—"
+#   STATUS: ❌ PLACEHOLDER DATA — all values hardcoded to zero
+
+# R-129: Token warning email MUST include actual tokens_used and tokens_total.
+#   WHY: "Your usage is at 80%" with tokens_used=0 is confusing and useless.
+#   WHERE: app/tasks/email_task.py:70-76 — tokens_used=0, tokens_total=0
+#   STATUS: ❌ PLACEHOLDER DATA
+
+# R-130: Link health check MUST NOT follow redirects to internal/private IPs (SSRF).
+#   WHY: An author could set purchase_url to http://169.254.169.254/metadata (AWS IMDS).
+#   WHERE: app/tasks/link_health_task.py:34 — follow_redirects=True with NO IP blocklist
+#   STATUS: ❌ NOT PROTECTED — follows redirects blindly, including to internal IPs
+
+# R-131: Celery Beat MUST include the backup task in its schedule.
+#   WHY: backup_task.py exists but is NOT registered in beat_schedule.
+#   WHERE: app/tasks/celery_app.py:40-66
+#   STATUS: ❌ MISSING — backup task exists (backup_task.py) but never scheduled
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §20. STARTUP & INITIALIZATION
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-132: Schema migrations MUST NOT use raw ALTER TABLE in application startup code.
+#   WHY: Raw f-string ALTER TABLE is fragile, non-reversible, and can silently fail.
+#     Also, f"ALTER TABLE {table} ADD COLUMN {col}" has SQL injection risk if table/col
+#     values ever come from untrusted input (currently hardcoded, but bad pattern).
+#   WHERE: app/main.py:78-101 — manual ALTER TABLE loop in _init_db()
+#   STATUS: ❌ Uses raw DDL instead of Alembic (blocked until R-048 is done)
+
+# R-133: OpenAPI docs (/docs, /redoc) MUST be disabled or auth-gated in production.
+#   WHY: Public OpenAPI documentation maps every endpoint, parameter, and schema
+#     for an attacker. This is the #1 reconnaissance tool.
+#   WHERE: app/main.py:155-156 — docs_url="/docs", redoc_url="/redoc" always enabled
+#   STATUS: ❌ PUBLIC — anyone can browse full API docs
+
+# R-134: SuperAdmin seed MUST generate TOTP secret on first creation.
+#   WHY: If R-007 (TOTP enforcement) is implemented but no totp_secret exists
+#     on the seeded SuperAdmin, they'll be permanently locked out.
+#   WHERE: app/main.py:131-139 — creates User without totp_secret
+#   STATUS: ❌ NOT IMPLEMENTED — User model has no totp_secret column either
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# §21. DEPLOYMENT — DOCKER & SERVICES
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# R-135: docker-compose.yml MUST NOT use deprecated 'version' key.
+#   WHY: Docker Compose v2+ ignores the version key; keeping it causes warnings
+#     and confuses developers about which spec is being used.
+#   WHERE: docker-compose.yml:1 — version: "3.9"
+#   STATUS: ⚠️ Works but deprecated — remove the line
+
+# R-136: Flower (Celery monitoring) MUST require authentication.
+#   WHY: Flower exposes task names, arguments, worker status, and broker URLs.
+#   WHERE: docker-compose.yml:123 — celery flower started with no auth flags
+#   STATUS: ❌ NO AUTH — add --basic-auth=user:password or --auth=email
+
+# R-137: docker-compose api command MUST NOT use --reload in production.
+#   WHY: --reload enables code injection via filesystem writes and wastes CPU.
+#   WHERE: docker-compose.yml:79 — uvicorn ... --reload
+#   STATUS: ⚠️ PARTIAL — file is marked "Development" but no production override exists
+
+# R-138: User cascade delete MUST clean up ChromaDB collections.
+#   WHY: When SuperAdmin deletes an author, DB records cascade-delete but
+#     ChromaDB collections (vector data) remain orphaned forever, wasting storage.
+#   WHERE: app/services/superadmin_service.py:135-183 — deletes user but no ChromaDB cleanup
+#   STATUS: ❌ ORPHANED VECTORS — ChromaDB collections survive author deletion
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# SUMMARY: 138 RULES
+# ═══════════════════════════════════════════════════════════════════════════════
+# ✅ Implemented:    70 rules
+# ❌ Not Implemented: 47 rules (must fix)
+# ⚠️ Partial:        21 rules (needs improvement)
+# ═════════════════════════════════════════════��═════════════════════════════════

.github/workflows/ci.yml

@@ -35,6 +35,32 @@ jobs:
     name: Tests
     runs-on: ubuntu-latest
     needs: lint
+
+    services:
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_DB: test_authorbot
+          POSTGRES_USER: authorbot
+          POSTGRES_PASSWORD: testpass
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U authorbot -d test_authorbot"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
     steps:
       - uses: actions/checkout@v4
 
@@ -46,15 +72,15 @@ jobs:
       - name: Install dependencies
         run: pip install -r requirements.txt
 
-      - name: Run unit tests
+      - name: Run unit + integration tests
         env:
           JWT_SECRET_KEY: "ci-test-secret-key-not-for-production"
-          DATABASE_URL: "sqlite+aiosqlite:///./test.db"
+          DATABASE_URL: "postgresql+asyncpg://authorbot:testpass@localhost:5432/test_authorbot"
           REDIS_URL: "redis://localhost:6379"
           OPENAI_API_KEY: "sk-test-fake-key"
           CHROMA_PERSIST_DIR: "./test_chroma"
         run: |
-          pytest tests/ -v --tb=short --cov=app --cov-report=xml -x || true
+          pytest tests/ -v --tb=short --cov=app --cov-report=xml --cov-fail-under=80 -x
 
       - name: Upload coverage
         if: always()

Dockerfile

@@ -32,7 +32,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 WORKDIR /app
 ENV PYTHONPATH=/app
 ENV DATABASE_URL=sqlite+aiosqlite:////data/db.sqlite
-ENV REDIS_URL=redis://localhost:6379/0
+ENV REDIS_URL=redis://:authorbotredis@localhost:6379/0
 ENV CHROMA_CLIENT_MODE=persistent
 ENV CHROMA_PERSIST_DIR=/data/chroma
 ENV UPLOAD_STORAGE_PATH=/data/uploads
@@ -46,7 +46,7 @@ COPY static/ ./static/
 COPY app.py .
 
 RUN mkdir -p /data/chroma /data/uploads /data/sessions /data/redis && \
-    printf 'dir /data/redis\nbind 127.0.0.1\nport 6379\ndaemonize yes\nlogfile /dev/null\n' > /app/redis-hf.conf
+    printf 'dir /data/redis\nbind 127.0.0.1\nport 6379\ndaemonize yes\nlogfile /dev/null\nrequirepass authorbotredis\nappendonly yes\nappendfsync everysec\n' > /app/redis-hf.conf
 
 RUN adduser --disabled-password --gecos "" --uid 1000 appuser && \
     chown -R appuser:appuser /app /data

app/admin/router.py

@@ -28,6 +28,13 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from app.dependencies import get_db, get_current_author_scoped, get_redis
 from app.repositories.book_repo import BookRepository
 from app.repositories.audit_repo import AuditRepository
+from app.schemas.admin import (
+    AnnotateRequest,
+    FlagRequest,
+    PasswordChangeRequest,
+    ProfileUpdate,
+    WidgetConfigUpdate,
+)
 
 router = APIRouter()
 
@@ -461,28 +468,20 @@ async def get_intent_distribution(
 @router.post("/{author_slug}/password")
 async def change_password(
     author_slug: str,
-    body: dict,
+    body: PasswordChangeRequest,
     current_user=Depends(get_current_author_scoped),
     db: AsyncSession = Depends(get_db),
 ):
-    """Self-service password change."""
+    """Self-service password change. R-010: Validates via Pydantic schema."""
     import bcrypt
-    current_password = body.get("current_password", "")
-    new_password = body.get("new_password", "")
-    if not current_password or not new_password:
-        from fastapi import HTTPException
-        raise HTTPException(400, "Both current_password and new_password are required")
-    if len(new_password) < 8:
-        from fastapi import HTTPException
-        raise HTTPException(400, "New password must be at least 8 characters")
     try:
-        valid = bcrypt.checkpw(current_password.encode(), current_user.password_hash.encode())
+        valid = bcrypt.checkpw(body.current_password.encode(), current_user.password_hash.encode())
     except Exception:
         valid = False
     if not valid:
         from fastapi import HTTPException
         raise HTTPException(400, "Current password is incorrect")
-    current_user.password_hash = bcrypt.hashpw(new_password.encode(), bcrypt.gensalt(12)).decode()
+    current_user.password_hash = bcrypt.hashpw(body.new_password.encode(), bcrypt.gensalt(12)).decode()
     await db.commit()
     return {"message": "Password updated"}
 
@@ -509,25 +508,22 @@ async def get_widget_config(
 @router.put("/{author_slug}/widget-config")
 async def update_widget_config(
     author_slug: str,
-    body: dict,
+    body: WidgetConfigUpdate,
     current_user=Depends(get_current_author_scoped),
     db: AsyncSession = Depends(get_db),
 ):
-    """Update widget configuration."""
-    allowed = {
-        "bot_name": ("bot_name", str, 100),
-        "welcome_message": ("welcome_message", str, 500),
-        "theme": ("widget_theme", str, 50),
-        "position": ("widget_position", str, 20),
-        "auto_open_delay": ("widget_auto_open_delay", int, None),
-        "is_active": ("chatbot_is_active", bool, None),
+    """Update widget configuration. R-029: Validated via Pydantic schema."""
+    update_map = {
+        "bot_name": "bot_name",
+        "welcome_message": "welcome_message",
+        "theme": "widget_theme",
+        "position": "widget_position",
+        "auto_open_delay": "widget_auto_open_delay",
+        "is_active": "chatbot_is_active",
     }
-    for key, (attr, typ, maxlen) in allowed.items():
-        if key in body:
-            val = body[key]
-            if typ == str and maxlen and len(str(val)) > maxlen:
-                from fastapi import HTTPException
-                raise HTTPException(400, f"{key} exceeds max length {maxlen}")
+    for field_name, attr in update_map.items():
+        val = getattr(body, field_name, None)
+        if val is not None:
             setattr(current_user, attr, val)
     await db.commit()
     return {"message": "Widget config updated"}
@@ -554,19 +550,19 @@ async def get_profile(
 @router.put("/{author_slug}/profile")
 async def update_profile(
     author_slug: str,
-    body: dict,
+    body: ProfileUpdate,
     current_user=Depends(get_current_author_scoped),
     db: AsyncSession = Depends(get_db),
 ):
-    """Update author profile."""
-    if "full_name" in body:
-        current_user.full_name = str(body["full_name"])[:255]
-    if "website" in body:
-        current_user.website_url = str(body["website"])[:500]
-    if "bio" in body:
-        current_user.bio = str(body["bio"])[:2000]
-    if "timezone" in body:
-        current_user.timezone = str(body["timezone"])[:100]
+    """Update author profile. R-029: Validated via Pydantic schema."""
+    if body.full_name is not None:
+        current_user.full_name = body.full_name
+    if body.website is not None:
+        current_user.website_url = body.website
+    if body.bio is not None:
+        current_user.bio = body.bio
+    if body.timezone is not None:
+        current_user.timezone = body.timezone
     await db.commit()
     return {"message": "Profile updated"}
 
@@ -662,11 +658,11 @@ async def get_embed_token(
     Token is regenerated from stored grant data — never stored in plaintext.
     """
     from sqlalchemy import select
-    from datetime import datetime
+    from datetime import datetime, timezone
     from app.models.client_access import ClientAccess
     from app.core.access.token_crypto import create_subscription_token
 
-    now = datetime.utcnow()  # naive — matches SQLite stored datetimes
+    now = datetime.now(timezone.utc)  # R-051: timezone-aware UTC
     result = await db.execute(
         select(ClientAccess)
         .where(
@@ -860,18 +856,22 @@ async def annotate_message(
     author_slug: str,
     session_id: str,
     message_id: str,
-    body: dict,
+    body: AnnotateRequest,
     current_user=Depends(get_current_author_scoped),
     db: AsyncSession = Depends(get_db),
 ):
-    """Add admin annotation to a chat message (append-only)."""
+    """Add admin annotation to a chat message (append-only). R-029: Schema validated."""
     from sqlalchemy import select
-    from app.models.chat_session import ChatMessage
+    from app.models.chat_session import ChatMessage, ChatSession
 
+    # R-040: Verify session ownership via JOIN to prevent IDOR
     result = await db.execute(
-        select(ChatMessage).where(
+        select(ChatMessage)
+        .join(ChatSession, ChatMessage.session_id == ChatSession.id)
+        .where(
             ChatMessage.id == message_id,
             ChatMessage.session_id == session_id,
+            ChatSession.author_id == current_user.id,
         )
     )
     msg = result.scalar_one_or_none()
@@ -879,10 +879,7 @@ async def annotate_message(
         from fastapi import HTTPException
         raise HTTPException(404, "Message not found")
 
-    annotation = str(body.get("annotation", ""))[:2000]
-    if not annotation:
-        from fastapi import HTTPException
-        raise HTTPException(400, "Annotation text required")
+    annotation = body.annotation
 
     # Append-only: prepend timestamp + existing
     from datetime import datetime, timezone
@@ -898,24 +895,24 @@ async def flag_message(
     author_slug: str,
     session_id: str,
     message_id: str,
-    body: dict,
+    body: FlagRequest,
     current_user=Depends(get_current_author_scoped),
     db: AsyncSession = Depends(get_db),
 ):
-    """Flag a message as spam, quality issue, or escalation."""
+    """Flag a message as spam, quality issue, or escalation. R-029: Schema validated."""
     from sqlalchemy import select
-    from app.models.chat_session import ChatMessage
+    from app.models.chat_session import ChatMessage, ChatSession
 
-    valid_flags = ["spam", "quality", "escalation", None]
-    flag_type = body.get("flag_type")
-    if flag_type not in valid_flags:
-        from fastapi import HTTPException
-        raise HTTPException(400, f"Invalid flag. Must be one of: {valid_flags}")
+    # flag_type validated by FlagRequest Pydantic Literal — "spam", "quality", "escalation", or None
 
+    # R-040: Verify session ownership via JOIN to prevent IDOR
     result = await db.execute(
-        select(ChatMessage).where(
+        select(ChatMessage)
+        .join(ChatSession, ChatMessage.session_id == ChatSession.id)
+        .where(
             ChatMessage.id == message_id,
             ChatMessage.session_id == session_id,
+            ChatSession.author_id == current_user.id,
         )
     )
     msg = result.scalar_one_or_none()
@@ -923,9 +920,9 @@ async def flag_message(
         from fastapi import HTTPException
         raise HTTPException(404, "Message not found")
 
-    msg.flag_type = flag_type
+    msg.flag_type = body.flag_type
     await db.commit()
-    return {"message": "Flag updated", "flag_type": flag_type}
+    return {"message": "Flag updated", "flag_type": body.flag_type}
 
 
 

app/api/chat.py

@@ -216,24 +216,7 @@ async def get_history(
     return {"session_id": session_id, "history": ctx.history, "turn_count": ctx.turn_count}
 
 
-@router.post("/{author_slug}/session/rate")
-async def rate_session(
-    author_slug: str,
-    session_id: str,
-    rating: int,
-    author=Depends(get_subscription_author),
-    db: AsyncSession = Depends(get_db),
-):
-    """Submit a star rating (1–5) for a chat session."""
-    from app.models.chat_session import ChatSession
-    from sqlalchemy import update
-    await db.execute(
-        update(ChatSession)
-        .where(ChatSession.id == session_id, ChatSession.author_id == author.id)
-        .values(rating=rating)
-    )
-    await db.commit()
-    return {"message": "Rating saved", "rating": rating}
+# R-046: First rate_session definition removed — was duplicate of L346 which has proper body validation
 
 
 @router.post("/{author_slug}/session/reset")
@@ -261,7 +244,19 @@ async def ingestion_events(
         channel = f"ingestion:{author.id}"
         await pubsub.subscribe(channel)
         try:
+            # R-023: Max connection timeout to prevent connection exhaustion
+            import time as _time
+            deadline = _time.monotonic() + 300  # 5 minute max
+            heartbeat_interval = 30
+            last_heartbeat = _time.monotonic()
             async for message in pubsub.listen():
+                now = _time.monotonic()
+                if now >= deadline:
+                    yield 'data: {"type": "timeout"}\n\n'
+                    break
+                if now - last_heartbeat > heartbeat_interval:
+                    yield ": heartbeat\n\n"
+                    last_heartbeat = now
                 if message["type"] == "message":
                     yield f"data: {message['data']}\n\n"
         finally:

app/api/ingest.py

@@ -8,10 +8,8 @@ Saves uploaded file to disk first, then passes the path to services
 that expect file_path (not raw bytes).
 """
 
-import asyncio
 import json
 import os
-import tempfile
 from pathlib import Path
 
 from fastapi import APIRouter, Depends, File, UploadFile, HTTPException
@@ -40,7 +38,13 @@ async def upload_book(
     redis=Depends(get_redis),
 ):
     """Upload a book file (PDF/EPUB/DOCX/TXT) and start async ingestion."""
-    contents = await file.read()
+    # R-024: Chunked upload — reject oversized files BEFORE reading into memory
+    MAX_UPLOAD_BYTES = cfg.UPLOAD_MAX_FILE_SIZE_MB * 1024 * 1024
+    contents = bytearray()
+    while chunk := await file.read(64 * 1024):  # 64KB chunks
+        contents.extend(chunk)
+        if len(contents) > MAX_UPLOAD_BYTES:
+            raise HTTPException(413, f"File too large. Maximum: {cfg.UPLOAD_MAX_FILE_SIZE_MB}MB")
     filename = file.filename or "upload"
 
     book_repo = BookRepository(db)
@@ -73,15 +77,14 @@ async def upload_book(
     })
     await db.commit()
 
-    asyncio.create_task(
-        _run_ingestion(
-            file_path=str(tmp_path),
-            book_id=book.id,
-            author_id=current_user.id,
-            title=book.title,
-            redis=redis,
-            db=db,
-        )
+    # R-082: Dispatch to Celery for crash resilience, retries, and worker isolation
+    from app.tasks.ingestion_task import process_document
+    process_document.delay(
+        document_id=doc.id,
+        author_id=current_user.id,
+        book_id=book.id,
+        file_path=str(tmp_path),
+        file_extension=suffix.lstrip("."),
     )
 
     return {"book_id": book.id, "doc_id": doc.id, "status": "processing"}
@@ -96,11 +99,25 @@ async def ingestion_progress(
 ):
     """SSE stream for real-time ingestion progress."""
     async def event_stream():
-        channel = f"ingestion:{current_user.id}:{book_id}"
+        # R-084: Unified channel pattern between Celery and admin SSE
+        channel = f"ingestion:{current_user.id}"
         pubsub = redis.pubsub()
         await pubsub.subscribe(channel)
         try:
+            # R-023: Max connection timeout to prevent connection exhaustion
+            import asyncio as _aio
+            import time as _time
+            deadline = _time.monotonic() + 300  # 5 minute max
+            heartbeat_interval = 30
+            last_heartbeat = _time.monotonic()
             async for message in pubsub.listen():
+                now = _time.monotonic()
+                if now >= deadline:
+                    yield 'data: {"stage": "timeout"}\n\n'
+                    break
+                if now - last_heartbeat > heartbeat_interval:
+                    yield ": heartbeat\n\n"
+                    last_heartbeat = now
                 if message["type"] == "message":
                     yield f"data: {message['data']}\n\n"
                     data = json.loads(message["data"])

app/api/schemas_router.py

@@ -8,7 +8,7 @@ Routes:
   GET  /api/auth/me
 """
 
-from fastapi import APIRouter, Depends, Request, Response
+from fastapi import APIRouter, Depends, Header, Request, Response
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.config import get_settings
@@ -56,8 +56,13 @@ async def login(payload: LoginRequest, response: Response, db: AsyncSession = De
 
 
 @router.post("/auth/refresh", response_model=TokenResponse, tags=["Auth"])
-async def refresh(request: Request, response: Response, db: AsyncSession = Depends(get_db)):
-    """Issue new JWT token pair."""
+async def refresh(
+    request: Request,
+    response: Response,
+    authorization: str = Header(default=""),
+    db: AsyncSession = Depends(get_db),
+):
+    """Issue new JWT token pair and blacklist the old access token."""
     from fastapi import HTTPException
 
     refresh_token = request.cookies.get("refresh_token")
@@ -70,16 +75,52 @@ async def refresh(request: Request, response: Response, db: AsyncSession = Depen
     if not refresh_token:
         raise HTTPException(401, "Refresh token required")
 
+    # R-004: Blacklist old access token before issuing new pair
+    if authorization and authorization.startswith("Bearer "):
+        old_token = authorization.removeprefix("Bearer ").strip()
+        try:
+            from app.core.access.token_crypto import decode_jwt
+            from app.core.access.jwt_blacklist import blacklist_token
+            from app.dependencies import get_redis
+            old_payload = decode_jwt(old_token)
+            old_jti = old_payload.get("jti")
+            if old_jti:
+                ttl = max(int(old_payload.get("exp", 0) - __import__("time").time()), 1)
+                redis = await get_redis()
+                await blacklist_token(redis, old_jti, ttl)
+        except Exception:
+            pass  # Best-effort blacklisting
+
     result = await AuthService(db).refresh_tokens(refresh_token)
     _set_refresh_cookie(response, result["refresh_token"])
     return result
 
 
 @router.post("/auth/logout", status_code=204, tags=["Auth"])
-async def logout(response: Response, _=Depends(get_current_user)):
-    """Invalidate refresh token cookie."""
+async def logout(
+    response: Response,
+    authorization: str = Header(default=""),
+    _=Depends(get_current_user),
+):
+    """Invalidate refresh token cookie and blacklist current JWT."""
     response.delete_cookie("refresh_token", path="/")
 
+    # R-005: Blacklist current access token in Redis
+    if authorization and authorization.startswith("Bearer "):
+        token = authorization.removeprefix("Bearer ").strip()
+        try:
+            from app.core.access.token_crypto import decode_jwt
+            from app.core.access.jwt_blacklist import blacklist_token
+            from app.dependencies import get_redis
+            payload = decode_jwt(token)
+            jti = payload.get("jti")
+            if jti:
+                ttl = max(int(payload.get("exp", 0) - __import__("time").time()), 1)
+                redis = await get_redis()
+                await blacklist_token(redis, jti, ttl)
+        except Exception:
+            pass  # Best-effort blacklisting
+
 
 @router.get("/auth/me", response_model=UserResponse, tags=["Auth"])
 async def get_me(current_user=Depends(get_current_user)):

app/config.py

@@ -156,6 +156,9 @@ class Settings(BaseSettings):
     CELERY_BROKER_URL: str = Field(default="redis://localhost:6379/1")
     CELERY_RESULT_BACKEND: str = Field(default="redis://localhost:6379/2")
 
+    # ─── Observability ────────────────────────────────────
+    SENTRY_DSN: str | None = None  # R-100: Set via env to enable error tracking
+
     @field_validator("SECRET_KEY")
     @classmethod
     def secret_key_must_be_strong(cls, v: str) -> str:

app/core/access/jwt_blacklist.py

@@ -0,0 +1,31 @@
+"""Author RAG Chatbot SaaS — JWT Blacklist (Redis-backed).
+
+Used for logout and refresh token rotation.
+When a user logs out or refreshes, the old JWT's jti is added to Redis
+with a TTL equal to the remaining token lifetime.
+
+R-004: Refresh must invalidate old token.
+R-005: Logout must blacklist current token.
+"""
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+BLACKLIST_PREFIX = "jwt_blacklisted:"
+
+
+async def blacklist_token(redis, jti: str, ttl_seconds: int) -> None:
+    """Add a JWT ID to the blacklist with TTL = remaining token lifetime."""
+    if not jti:
+        return
+    key = f"{BLACKLIST_PREFIX}{jti}"
+    await redis.setex(key, max(ttl_seconds, 1), "1")
+    logger.debug("JWT blacklisted", jti=jti[:8], ttl=ttl_seconds)
+
+
+async def is_blacklisted(redis, jti: str) -> bool:
+    """Check if a JWT ID has been blacklisted."""
+    if not jti:
+        return False
+    return bool(await redis.exists(f"{BLACKLIST_PREFIX}{jti}"))

app/core/access/token_crypto.py

@@ -9,6 +9,7 @@ import hashlib
 import hmac
 import json
 import time
+import uuid
 from base64 import urlsafe_b64decode, urlsafe_b64encode
 from datetime import datetime, timedelta, timezone
 from typing import Any
@@ -57,6 +58,7 @@ def create_access_token(subject: str, extra_claims: dict[str, Any] | None = None
     expire = now + timedelta(minutes=cfg.ACCESS_TOKEN_EXPIRE_MINUTES)
     payload = {
         "sub": subject,
+        "jti": uuid.uuid4().hex,  # R-004/R-005: JWT ID for blacklisting
         "iat": now,
         "exp": expire,
         "type": "access",
@@ -78,6 +80,7 @@ def create_refresh_token(subject: str) -> str:
     expire = now + timedelta(days=cfg.REFRESH_TOKEN_EXPIRE_DAYS)
     payload = {
         "sub": subject,
+        "jti": uuid.uuid4().hex,  # R-004/R-005: JWT ID for blacklisting
         "iat": now,
         "exp": expire,
         "type": "refresh",

app/dependencies.py

@@ -127,6 +127,19 @@ async def _get_authenticated_user(
     except Exception:
         raise HTTPException(status_code=401, detail="Could not validate token")
 
+    # R-004/R-005: Check if JWT has been blacklisted (logout/refresh rotation)
+    jti = payload.get("jti")
+    if jti:
+        try:
+            from app.core.access.jwt_blacklist import is_blacklisted
+            redis = await get_redis()
+            if await is_blacklisted(redis, jti):
+                raise HTTPException(status_code=401, detail="Token has been revoked")
+        except HTTPException:
+            raise
+        except Exception:
+            pass  # Redis down: fail-open for blacklist check
+
     user_id: str = payload.get("sub")
     if not user_id:
         raise HTTPException(status_code=401, detail="Token missing subject claim")
@@ -175,10 +188,23 @@ async def get_current_author_scoped(
     return current_user
 
 
-async def get_current_superadmin(current_user=Depends(get_current_user)):
-    """Ensure the authenticated user is a SuperAdmin."""
+async def get_current_superadmin(
+    current_user=Depends(get_current_user),
+    x_totp_code: str = Header(default="", alias="X-TOTP-Code"),
+):
+    """Ensure the authenticated user is a SuperAdmin with valid TOTP."""
     if current_user.role != "superadmin":
         raise HTTPException(status_code=403, detail="SuperAdmin access required")
+
+    # R-007: TOTP verification required on every SuperAdmin request
+    from app.core.access.totp import verify_totp
+    if not x_totp_code:
+        raise HTTPException(status_code=403, detail="TOTP code required")
+    if not current_user.totp_secret:
+        raise HTTPException(status_code=403, detail="TOTP not configured for this account")
+    if not verify_totp(current_user.totp_secret, x_totp_code):
+        raise HTTPException(status_code=403, detail="Invalid TOTP code")
+
     return current_user
 
 
@@ -208,7 +234,7 @@ async def get_subscription_author(
     except SubscriptionNotFoundError:
         raise HTTPException(status_code=403, detail="No active subscription. Contact support.")
     except BudgetExhaustedError:
-        raise HTTPException(status_code=403, detail="Monthly token budget exhausted")
+        raise  # R-016: Let global exception handler in main.py return HTTP 200 with friendly message
 
 
 # ─── Health Check ─────────────────────────────────────────────────────────────

app/main.py

@@ -90,6 +90,7 @@ async def _init_db() -> None:
         ("chat_messages", "flag_type", "VARCHAR(20)"),
         ("chat_messages", "user_feedback", "VARCHAR(10)"),
         ("client_access", "tokens_used", "INTEGER NOT NULL DEFAULT 0"),
+        ("users", "totp_secret", "VARCHAR(64)"),  # R-134: TOTP for SuperAdmin
     ]
     async with engine.begin() as conn:
         from sqlalchemy import text
@@ -128,16 +129,20 @@ async def _seed_superadmin(cfg) -> None:
                 logger.info("Superadmin already exists", email=cfg.SUPERADMIN_EMAIL)
             return
 
+        # R-134: Generate TOTP secret so TOTP enforcement doesn't lock out SuperAdmin
+        from app.core.access.totp import generate_totp_secret
         sa = User(
             email=cfg.SUPERADMIN_EMAIL,
             password_hash=hash_password(cfg.SUPERADMIN_PASSWORD),
             role="superadmin",
             full_name="Super Admin",
             is_active=True,
+            totp_secret=generate_totp_secret(),
         )
         db.add(sa)
         await db.commit()
-        logger.info("Superadmin account created", email=cfg.SUPERADMIN_EMAIL)
+        logger.info("Superadmin account created", email=cfg.SUPERADMIN_EMAIL,
+                    totp_setup_required=True)
 
 
 
@@ -145,6 +150,10 @@ def create_app() -> FastAPI:
     """Create and configure the FastAPI application."""
     cfg = get_settings()
 
+    # R-133: Disable OpenAPI docs in production to prevent API reconnaissance
+    docs = "/docs" if cfg.APP_ENV != "production" else None
+    redoc = "/redoc" if cfg.APP_ENV != "production" else None
+
     app = FastAPI(
         title="Author RAG — AI Book Sales Chatbot SaaS",
         description=(
@@ -152,11 +161,24 @@ def create_app() -> FastAPI:
             "on any author's website. Powered by a 12-step RAG pipeline."
         ),
         version="1.0.0",
-        docs_url="/docs",
-        redoc_url="/redoc",
+        docs_url=docs,
+        redoc_url=redoc,
         lifespan=lifespan,
     )
 
+    # R-100: Sentry error tracking (optional — only in Docker)
+    if hasattr(cfg, 'SENTRY_DSN') and cfg.SENTRY_DSN:
+        try:
+            import importlib
+            sentry_sdk = importlib.import_module("sentry_sdk")
+            sentry_sdk.init(
+                dsn=cfg.SENTRY_DSN,
+                traces_sample_rate=0.1,
+                environment=cfg.APP_ENV,
+            )
+        except (ImportError, Exception):
+            logger.warning("sentry-sdk not installed — error tracking disabled")
+
     _register_middleware(app, cfg)
     _register_exception_handlers(app)
     _register_routers(app)
@@ -171,6 +193,13 @@ def _register_middleware(app: FastAPI, cfg) -> None:
     app.add_middleware(SecurityHeadersMiddleware)
     app.add_middleware(RateLimitMiddleware)
 
+    # R-099: Prometheus metrics middleware
+    try:
+        from app.middleware.metrics import PrometheusMiddleware
+        app.add_middleware(PrometheusMiddleware)
+    except ImportError:
+        pass
+
     cors_origins = cfg.ALLOWED_ORIGINS if cfg.APP_ENV == "production" else ["*"]
     app.add_middleware(
         CORSMiddleware,
@@ -291,7 +320,7 @@ def _register_public_routes(app: FastAPI) -> None:
         return FileResponse(
             WIDGET_TEMPLATE,
             headers={
-                "Access-Control-Allow-Origin": "*",
+                # R-125: Removed wildcard CORS — widget test page should not be embeddable by any domain
                 "Cache-Control": "no-cache, no-store, must-revalidate",
             },
         )
@@ -302,6 +331,17 @@ def _register_public_routes(app: FastAPI) -> None:
         from app.dependencies import check_health
         return await check_health()
 
+    @app.get("/metrics", include_in_schema=False)
+    async def prometheus_metrics():
+        """R-099: Prometheus metrics endpoint."""
+        from starlette.responses import Response
+        try:
+            from app.middleware.metrics import get_metrics_response
+            body, content_type = get_metrics_response()
+            return Response(content=body, media_type=content_type)
+        except ImportError:
+            return Response(content=b"# metrics not available\n", media_type="text/plain")
+
 
 # Application instance
 app = create_app()

app/middleware/metrics.py

@@ -0,0 +1,122 @@
+"""Author RAG Chatbot SaaS — Prometheus Metrics Middleware.
+
+R-099: Prometheus /metrics endpoint MUST be configured.
+R-102: Per-step pipeline latency MUST be tracked.
+
+Exposes request counts, latencies, and business metrics via /metrics endpoint.
+"""
+
+import time
+
+import structlog
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+logger = structlog.get_logger(__name__)
+
+try:
+    from prometheus_client import Counter, Histogram, generate_latest, CONTENT_TYPE_LATEST
+
+    # ─── HTTP Metrics ─────────────────────────────────────────────────────────
+    REQUEST_COUNT = Counter(
+        "http_requests_total",
+        "Total HTTP requests",
+        ["method", "path", "status"],
+    )
+    REQUEST_LATENCY = Histogram(
+        "http_request_duration_seconds",
+        "HTTP request latency in seconds",
+        ["method", "path"],
+        buckets=[0.01, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0],
+    )
+
+    # ─── Business Metrics ─────────────────────────────────────────────────────
+    CHAT_TURNS = Counter(
+        "chat_turns_total",
+        "Total chat turns processed",
+        ["author_id"],
+    )
+    TOKEN_USAGE = Counter(
+        "tokens_used_total",
+        "Total LLM tokens consumed",
+        ["author_id"],
+    )
+    PIPELINE_STEP_LATENCY = Histogram(
+        "rag_pipeline_step_duration_ms",
+        "RAG pipeline per-step latency in milliseconds",
+        ["step"],
+        buckets=[1, 5, 10, 25, 50, 100, 250, 500, 1000, 5000],
+    )
+    INGESTION_COUNT = Counter(
+        "document_ingestions_total",
+        "Total document ingestions",
+        ["status"],
+    )
+
+    PROMETHEUS_AVAILABLE = True
+
+except ImportError:
+    PROMETHEUS_AVAILABLE = False
+    logger.warning("prometheus_client not installed — /metrics endpoint disabled")
+
+
+class PrometheusMiddleware:
+    """ASGI middleware that tracks request counts and latencies."""
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        if not PROMETHEUS_AVAILABLE:
+            await self.app(scope, receive, send)
+            return
+
+        path = scope.get("path", "")
+        method = scope.get("method", "GET")
+
+        # Skip metrics endpoint itself to avoid recursion
+        if path == "/metrics":
+            await self.app(scope, receive, send)
+            return
+
+        # Normalize paths to avoid cardinality explosion
+        normalized = _normalize_path(path)
+
+        start = time.perf_counter()
+        status_code = 500  # Default in case of crash
+
+        async def send_wrapper(message):
+            nonlocal status_code
+            if message["type"] == "http.response.start":
+                status_code = message.get("status", 200)
+            await send(message)
+
+        try:
+            await self.app(scope, receive, send_wrapper)
+        finally:
+            duration = time.perf_counter() - start
+            REQUEST_COUNT.labels(method=method, path=normalized, status=str(status_code)).inc()
+            REQUEST_LATENCY.labels(method=method, path=normalized).observe(duration)
+
+
+def _normalize_path(path: str) -> str:
+    """Normalize URL paths to prevent label cardinality explosion.
+
+    Replaces UUIDs and dynamic segments with placeholders.
+    """
+    import re
+    # Replace UUIDs
+    path = re.sub(r'[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}', '{id}', path)
+    # Replace plain hex IDs (32+ chars)
+    path = re.sub(r'/[0-9a-f]{32,}', '/{id}', path)
+    return path
+
+
+def get_metrics_response():
+    """Generate Prometheus metrics response for /metrics endpoint."""
+    if not PROMETHEUS_AVAILABLE:
+        return b"# prometheus_client not installed\n", "text/plain"
+    return generate_latest(), CONTENT_TYPE_LATEST

app/middleware/security_headers.py

@@ -32,6 +32,11 @@ class SecurityHeadersMiddleware:
                     (b"x-xss-protection", b"1; mode=block"),
                     (b"referrer-policy", b"strict-origin-when-cross-origin"),
                     (b"permissions-policy", b"camera=(), microphone=(), geolocation=(), payment=()"),
+                    # R-043: CSP — primary XSS defense
+                    (b"content-security-policy",
+                     b"default-src 'self'; script-src 'self' 'unsafe-inline'; "
+                     b"style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; "
+                     b"connect-src 'self' https://api.openai.com; frame-ancestors 'none'"),
                 ]
                 if use_hsts:
                     security_headers.insert(

app/models/user.py

@@ -26,6 +26,7 @@ class User(Base, TimestampMixin):
     is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
     failed_login_attempts: Mapped[int] = mapped_column(Integer, default=0, nullable=False)
     locked_until: Mapped[str | None] = mapped_column(String(50), nullable=True)
+    totp_secret: Mapped[str | None] = mapped_column(String(64), nullable=True)  # R-134
 
     # Author profile fields
     full_name: Mapped[str | None] = mapped_column(String(255), nullable=True)

app/schemas/admin.py

@@ -0,0 +1,156 @@
+"""Author RAG Chatbot SaaS — Admin API Pydantic Schemas.
+
+R-029: ALL admin API endpoints MUST use Pydantic BaseModel schemas (NOT raw dict).
+R-010: Password change MUST validate via Pydantic schema.
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, EmailStr, Field, HttpUrl, field_validator
+
+
+# ─── Authentication ────────────────────────────────────────────────────────────
+
+class PasswordChangeRequest(BaseModel):
+    """R-010: Password change via validated schema."""
+    current_password: str = Field(min_length=1)
+    new_password: str = Field(min_length=8, max_length=128)
+
+    @field_validator("new_password")
+    @classmethod
+    def validate_new_password(cls, v: str) -> str:
+        """R-009: Enforce password complexity."""
+        if not any(c.isupper() for c in v):
+            raise ValueError("Password must contain at least one uppercase letter")
+        if not any(c.islower() for c in v):
+            raise ValueError("Password must contain at least one lowercase letter")
+        if not any(c.isdigit() for c in v):
+            raise ValueError("Password must contain at least one digit")
+        return v
+
+
+# ─── Widget Configuration ─────────────────────────────────────────────────────
+
+class WidgetConfigUpdate(BaseModel):
+    """Widget appearance and behavior settings."""
+    bot_name: str | None = Field(None, max_length=100)
+    welcome_message: str | None = Field(None, max_length=500)
+    theme: str | None = Field(None, pattern=r"^(midnight|ocean|forest|sunset|minimal)$")
+    position: str | None = Field(None, pattern=r"^(bottom-right|bottom-left)$")
+    auto_open_delay: int | None = Field(None, ge=0, le=60)
+    is_active: bool | None = None
+
+
+# ─── Author Profile ───────────────────────────────────────────────────────────
+
+class ProfileUpdate(BaseModel):
+    """Author profile update fields."""
+    full_name: str | None = Field(None, max_length=255)
+    website: str | None = Field(None, max_length=500)
+    bio: str | None = Field(None, max_length=2000)
+    timezone: str | None = Field(None, max_length=100)
+
+
+class PersonalityUpdate(BaseModel):
+    """Bot personality configuration."""
+    response_style: Literal["balanced", "formal", "casual", "enthusiastic"] | None = None
+    fallback_message: str | None = Field(None, max_length=500)
+    out_of_scope_message: str | None = Field(None, max_length=500)
+
+
+class NotificationUpdate(BaseModel):
+    """Notification preferences."""
+    weekly_digest: bool | None = None
+    token_alerts: bool | None = None
+    new_conversation: bool | None = None
+    subscription_expiry: bool | None = None
+
+
+# ─── Smart Links ──────────────────────────────────────────────────────────────
+
+class SmartLinkUpdate(BaseModel):
+    """R-031: URL validation on smart link updates."""
+    buy_url: str | None = Field(None, max_length=2000)
+    preview_url: str | None = Field(None, max_length=2000)
+
+    @field_validator("buy_url", "preview_url")
+    @classmethod
+    def validate_url_scheme(cls, v: str | None) -> str | None:
+        """R-031: Validate URL scheme to prevent SSRF."""
+        if v is None or v == "":
+            return v
+        if not v.startswith(("https://", "http://")):
+            raise ValueError("URL must start with https:// or http://")
+        return v
+
+
+# ─── Q&A ──────────────────────────────────────────────────────────────────────
+
+class QACreateRequest(BaseModel):
+    """Custom Q&A training data entry."""
+    question: str = Field(min_length=1, max_length=500)
+    answer: str = Field(min_length=1, max_length=2000)
+    book_id: str | None = None
+    priority: int = Field(default=0, ge=0, le=100)
+    category: str | None = Field(None, max_length=50)
+    match_threshold: float = Field(default=0.85, ge=0.5, le=1.0)
+
+
+class QAUpdateRequest(BaseModel):
+    """Custom Q&A update (partial)."""
+    question: str | None = Field(None, min_length=1, max_length=500)
+    answer: str | None = Field(None, min_length=1, max_length=2000)
+    priority: int | None = Field(None, ge=0, le=100)
+    category: str | None = Field(None, max_length=50)
+    match_threshold: float | None = Field(None, ge=0.5, le=1.0)
+
+
+# ─── Chat Annotations ─────────────────────────────────────────────────────────
+
+class AnnotateRequest(BaseModel):
+    """Admin annotation on a chat message."""
+    annotation: str = Field(min_length=1, max_length=2000)
+
+
+class FlagRequest(BaseModel):
+    """Flag a chat message for review."""
+    flag_type: Literal["spam", "quality", "escalation"] | None = None
+
+
+# ─── Visitor Interactions ─────────────────────────────────────────────────────
+
+class TrackClickRequest(BaseModel):
+    """Track purchase/preview link click."""
+    session_id: str
+    link_type: str = "purchase"
+    book_id: str | None = None
+
+
+class FeedbackRequest(BaseModel):
+    """Thumbs up/down on a bot message."""
+    session_id: str
+    message_index: int = Field(ge=0)
+    reaction: Literal["up", "down"]
+
+
+class RateSessionRequest(BaseModel):
+    """Star rating for a chat session."""
+    session_id: str
+    rating: int = Field(ge=1, le=5)
+
+
+# ─── Announcements ────────────────────────────────────────────────────────────
+
+class AnnouncementRequest(BaseModel):
+    """Author announcement message."""
+    message: str = Field(min_length=1, max_length=2000)
+
+
+# ─── SuperAdmin ───────────────────────────────────────────────────────────────
+
+class GrantByEmailRequest(BaseModel):
+    """SuperAdmin: grant access by email."""
+    author_email: EmailStr
+    plan: str = "monthly"
+    token_budget: int = Field(default=500000, ge=10000)
+    notes: str = ""

app/services/auth_service.py

@@ -51,8 +51,24 @@ class AuthService:
             Dict with access_token and user data.
 
         Raises:
-            ValueError: If email is already registered.
+            ValueError: If email is already registered or validation fails.
         """
+        # R-008: Validate email format
+        import re
+        email = email.lower().strip()
+        if not re.match(r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$', email):
+            raise ValueError("Invalid email format")
+
+        # R-009: Enforce password complexity
+        if len(password) < 8:
+            raise ValueError("Password must be at least 8 characters")
+        if not any(c.isupper() for c in password):
+            raise ValueError("Password must contain at least one uppercase letter")
+        if not any(c.islower() for c in password):
+            raise ValueError("Password must contain at least one lowercase letter")
+        if not any(c.isdigit() for c in password):
+            raise ValueError("Password must contain at least one digit")
+
         existing = await self._repo.get_by_email(email)
         if existing:
             raise ValueError("An account with this email already exists")

app/services/superadmin_service.py

@@ -165,6 +165,19 @@ class SuperAdminService:
 
         await clear_token_usage_counters(self._redis, author_id)
 
+        # R-138: Clean up ChromaDB collections to prevent orphaned vectors
+        try:
+            from app.core.chroma_client import get_chroma_client
+            chroma = get_chroma_client()
+            author_prefix = f"a{author_id.replace('-', '')[:12]}"
+            for col in chroma.list_collections():
+                col_name = col.name if hasattr(col, 'name') else str(col)
+                if col_name.startswith(author_prefix):
+                    chroma.delete_collection(col_name)
+                    logger.info("Deleted ChromaDB collection", collection=col_name)
+        except Exception as e:
+            logger.warning("ChromaDB cleanup failed during author delete", error=str(e))
+
         email = author.email
         name = author.full_name or email
 
@@ -395,8 +408,8 @@ class SuperAdminService:
             raise ValueError("Cannot extend a revoked subscription — create a new grant instead")
 
         # Extend from NOW if already expired, otherwise from current expiry
-        # Use naive utcnow() to match SQLite naive datetimes
-        now = datetime.utcnow()
+        # R-051: Use timezone-aware UTC datetime
+        now = datetime.now(timezone.utc)
         exp = access.expires_at
         if exp and exp.tzinfo is not None:
             exp = exp.replace(tzinfo=None)  # strip tz if stored as aware

app/services/token_budget.py

@@ -86,7 +86,16 @@ async def record_token_usage(
     if not access:
         return
 
-    access.tokens_used = (access.tokens_used or 0) + token_count
+    # R-014/R-052: Atomic SQL UPDATE instead of Python read-modify-write
+    from sqlalchemy import update
+    from app.models.client_access import ClientAccess as CA
+    await db.execute(
+        update(CA)
+        .where(CA.id == access.id, CA.author_id == access.author_id)
+        .values(tokens_used=CA.tokens_used + token_count)
+    )
+    await db.flush()
+    await db.refresh(access)
     budget = total_budget(access)
 
     if budget > 0 and access.tokens_used >= budget:

app/superadmin/router.py

@@ -47,7 +47,7 @@ def _err(e: Exception, context: str = "") -> JSONResponse:
     logger.error("SuperAdmin endpoint error", context=context, error=str(e), traceback=tb)
     return JSONResponse(
         status_code=500,
-        content={"detail": f"Internal error: {str(e)[:200]}"},
+        content={"detail": "An internal error occurred. Please try again or contact support."},
     )
 
 
@@ -74,9 +74,9 @@ async def superadmin_index():
 # ── Diagnostic (no auth) ─────────────────────────────────────────────────────
 
 @router.get("/diag")
-async def diagnostic():
-    """Public diagnostic endpoint — returns without auth to verify routing works."""
-    return {"status": "ok", "router": "superadmin", "auth": "not_checked"}
+async def diagnostic(superadmin=Depends(get_current_superadmin)):
+    """R-045: Diagnostic endpoint — requires SuperAdmin auth."""
+    return {"status": "ok", "router": "superadmin", "auth": "verified"}
 
 
 # ── Authors ───────────────────────────────────────────────────────────────────
@@ -467,7 +467,7 @@ async def list_all_grants(
         )
         rows = result.all()
 
-        now = datetime.utcnow()  # naive — matches SQLite stored datetimes
+        now = datetime.now(timezone.utc)  # R-051: timezone-aware UTC
         grants = []
         for access, user in rows:
             total_budget = access.token_budget + access.bonus_tokens
@@ -543,8 +543,8 @@ async def get_author_embed_token(
         if not user:
             raise HTTPException(404, "Author not found")
 
-        # Get their active grant — use naive utcnow to match SQLite naive datetimes
-        now = datetime.utcnow()
+        # R-051: Use timezone-aware UTC datetime
+        now = datetime.now(timezone.utc)
         result = await db.execute(
             select(ClientAccess)
             .where(

app/tasks/backup_task.py

@@ -14,6 +14,7 @@ from pathlib import Path
 import structlog
 
 from app.config import get_settings
+from app.tasks.celery_app import celery_app
 
 logger = structlog.get_logger(__name__)
 cfg = get_settings()
@@ -97,6 +98,7 @@ def _cleanup_old_backups(subdir: str) -> None:
             logger.info("Removed old backup", path=str(d))
 
 
+@celery_app.task(name="app.tasks.backup_task.run_backup")
 def run_backup() -> dict:
     """Run full backup cycle."""
     results = {

app/tasks/celery_app.py

@@ -22,6 +22,7 @@ celery_app = Celery(
         "app.tasks.expiry_check_task",
         "app.tasks.link_health_task",
         "app.tasks.geo_update_task",
+        "app.tasks.backup_task",  # R-131: Backup task must be in include list
     ],
 )
 
@@ -63,4 +64,9 @@ celery_app.conf.beat_schedule = {
         "task": "app.tasks.email_task.send_weekly_digests",
         "schedule": crontab(hour=9, minute=0, day_of_week=1),
     },
+    # R-106/R-131: Database backup: daily at 4am UTC
+    "daily-database-backup": {
+        "task": "app.tasks.backup_task.run_backup",
+        "schedule": crontab(hour=4, minute=0),
+    },
 }

app/tasks/link_health_task.py

@@ -56,6 +56,8 @@ async def _run():
 async def _check_url(client: httpx.AsyncClient, url: str) -> bool:
     """Check if a URL returns an OK response.
 
+    Includes SSRF protection — refuses to fetch internal/private IPs (R-130).
+
     Args:
         client: httpx async client.
         url: URL to check.
@@ -63,8 +65,28 @@ async def _check_url(client: httpx.AsyncClient, url: str) -> bool:
     Returns:
         True if URL is reachable (2xx/3xx), False otherwise.
     """
+    # R-130: SSRF protection — block internal/private IPs before fetching
+    if _is_internal_url(url):
+        logger.warning("Link health: blocked internal URL", url=url[:100])
+        return False
     try:
         response = await client.head(url)
         return response.status_code < 400
     except Exception:
         return False
+
+
+def _is_internal_url(url: str) -> bool:
+    """Return True if the URL resolves to an internal/private/loopback IP."""
+    import ipaddress
+    import socket
+    from urllib.parse import urlparse
+
+    try:
+        hostname = urlparse(url).hostname
+        if not hostname:
+            return True
+        ip = ipaddress.ip_address(socket.gethostbyname(hostname))
+        return ip.is_private or ip.is_loopback or ip.is_link_local or ip.is_reserved
+    except Exception:
+        return True  # Fail safe — block if we can't resolve

docker-compose.yml

@@ -1,4 +1,4 @@
-version: "3.9"
+# R-135: Removed deprecated version key (Docker Compose v2+ ignores it)
 
 # Author RAG Chatbot SaaS — Docker Compose (Development)
 # Usage: docker-compose up -d
@@ -120,7 +120,7 @@ services:
       - "5555:5555"
     depends_on:
       - redis
-    command: celery -A app.tasks.celery_app flower --port=5555
+    command: celery -A app.tasks.celery_app flower --port=5555 --basic-auth=admin:${FLOWER_PASSWORD:-changeme}
 
 volumes:
   postgres_data: