Sync from GitHub · 2026-09-24 23:37 UTC

main.py

@@ -11,13 +11,10 @@ load_dotenv()
 from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse
-from slowapi import Limiter, _rate_limit_exceeded_handler
-from slowapi.util import get_remote_address
-from slowapi.errors import RateLimitExceeded
 import firebase_admin
 from firebase_admin import credentials
 
-from routes import bff, chat, transcribe, documents, consultation, planning, admin
+from routes import bff, chat, transcribe, documents, consultation, planning, admin, account
 
 
 # ─── Firebase Admin SDK initialisation ───────────────────────────────────────
@@ -42,10 +39,6 @@ def _init_firebase():
 _init_firebase()
 
 
-# ─── Rate limiter ─────────────────────────────────────────────────────────────
-limiter = Limiter(key_func=get_remote_address, default_limits=["60/minute"])
-
-
 # ─── App lifecycle ────────────────────────────────────────────────────────────
 @asynccontextmanager
 async def lifespan(app: FastAPI):
@@ -65,9 +58,6 @@ app = FastAPI(
     lifespan=lifespan,
 )
 
-app.state.limiter = limiter
-app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
-
 
 # ─── CORS ─────────────────────────────────────────────────────────────────────
 allowed_origins_str = os.environ.get("ALLOWED_ORIGINS", "http://localhost:3000")
@@ -100,6 +90,7 @@ app.include_router(documents.router,     prefix="/api/documents",    tags=["Docu
 app.include_router(consultation.router, prefix="/api/consultation", tags=["Consultation"])
 app.include_router(planning.router,     prefix="/api/planning",     tags=["Planning"])
 app.include_router(admin.router,        prefix="/api/admin",        tags=["Admin"])
+app.include_router(account.router,      prefix="/api/account",      tags=["Account"])
 
 
 # ─── Health check (unauthenticated) ──────────────────────────────────────────

requirements.txt

@@ -3,7 +3,6 @@ uvicorn[standard]==0.30.6
 python-dotenv==1.0.1
 firebase-admin==6.5.0
 groq==0.11.0
-slowapi==0.1.9
 python-multipart==0.0.12
 pydantic==2.9.2
 httpx==0.27.2

routes/account.py

@@ -0,0 +1,58 @@
+"""
+Account Routes — self-service actions on the caller's own account.
+
+Unlike routes/admin.py, these never take a target uid from the request — the
+uid always comes from the verified Firebase ID token, so a user can only ever
+act on their own account.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException
+from firebase_admin import auth as fb_auth, firestore
+from auth import verify_firebase_token
+
+router = APIRouter()
+
+
+def delete_all_user_data(uid: str) -> None:
+    """
+    Deletes every Firestore document owned by a user: each business's
+    subcollections, the business docs themselves, xpHistory, and the
+    user_data root doc. Shared by this self-delete route and
+    routes/admin.py's delete_user so the cascade is defined once.
+    """
+    db = firestore.client()
+    user_ref = db.collection("user_data").document(uid)
+
+    for biz in user_ref.collection("businesses").stream():
+        for sub in ["bff", "profile_output", "documents", "kanban", "milestones", "sessions", "team"]:
+            for sdoc in biz.reference.collection(sub).stream():
+                sdoc.reference.delete()
+        biz.reference.delete()
+
+    for entry in user_ref.collection("xpHistory").stream():
+        entry.reference.delete()
+
+    user_ref.delete()
+
+
+@router.delete("/me")
+def delete_own_account(user: dict = Depends(verify_firebase_token)):
+    """
+    Deletes the caller's own account: all Firestore data (via the Admin SDK,
+    which bypasses firestore.rules — user_data deletion is deliberately
+    backend-only, see firestore.rules' own comment) and the Firebase Auth
+    user record. The frontend re-authenticates the user with their password
+    immediately before calling this, as an extra confirmation step.
+    """
+    uid = user.get("uid")
+    if not uid:
+        raise HTTPException(status_code=401, detail="Unauthorized.")
+
+    delete_all_user_data(uid)
+
+    try:
+        fb_auth.delete_user(uid)
+    except fb_auth.UserNotFoundError:
+        pass  # already gone — not an error for a delete
+
+    return {"success": True}

routes/admin.py

@@ -15,6 +15,7 @@ from fastapi import APIRouter, HTTPException, Depends
 from pydantic import BaseModel
 from firebase_admin import auth as fb_auth, firestore
 from auth import verify_firebase_token
+from routes.account import delete_all_user_data
 
 router = APIRouter()
 
@@ -100,20 +101,11 @@ def delete_user(
 ):
     admin_uid = _verify_admin(user)
     if target_uid == admin_uid:
+        # Self-deletion as an admin goes through DELETE /api/account/me instead,
+        # same as any other user — this endpoint is for deleting *other* accounts.
         raise HTTPException(status_code=400, detail="Admins cannot delete their own account.")
 
-    db = firestore.client()
-
-    # Delete Firestore user data (businesses subcollection + root doc)
-    user_ref = db.collection("user_data").document(target_uid)
-    biz_docs = user_ref.collection("businesses").stream()
-    for biz in biz_docs:
-        # Delete nested subcollections of each business
-        for sub in ["bff", "profile_output", "documents", "kanban", "milestones", "sessions", "team"]:
-            for sdoc in biz.reference.collection(sub).stream():
-                sdoc.reference.delete()
-        biz.reference.delete()
-    user_ref.delete()
+    delete_all_user_data(target_uid)
 
     # Delete Firebase Auth account
     try:

routes/bff.py

@@ -3,6 +3,7 @@ from fastapi import APIRouter, HTTPException, Depends
 from pydantic import BaseModel
 from firebase_admin import firestore
 from auth import verify_firebase_token
+from utils.rate_limiter import with_rate_limit
 from utils.groq_client import call_groq_json, HEAVY_MODEL
 from utils.pinecone_client import query_book_context
 
@@ -125,7 +126,7 @@ def _call_groq_json(system_prompt: str, user_prompt: str) -> dict:
 @router.post("/generate-followups")
 def generate_followups(
     body: GenerateFollowupsRequest,
-    user: dict = Depends(verify_firebase_token),
+    user: dict = Depends(with_rate_limit("generation")),
 ):
     """
     After each BFF section is submitted, generates 3–5 personalized
@@ -195,7 +196,7 @@ Question types:
 @router.post("/generate-profile")
 def generate_profile(
     body: GenerateProfileRequest,
-    user: dict = Depends(verify_firebase_token),
+    user: dict = Depends(with_rate_limit("generation")),
 ):
     """
     Reads all completed BFF sections from Firestore and generates all 4

routes/chat.py

@@ -3,7 +3,7 @@ from fastapi import APIRouter, HTTPException, Depends
 from fastapi.responses import StreamingResponse
 from pydantic import BaseModel
 from firebase_admin import firestore
-from auth import verify_firebase_token
+from utils.rate_limiter import with_rate_limit
 from utils.groq_client import call_groq_stream, LIGHT_MODEL, HEAVY_MODEL
 from utils.pinecone_client import query_book_context
 
@@ -65,7 +65,7 @@ def _get_business_context(user_id: str, business_id: str) -> str:
 @router.post("/message")
 def chat_message(
     body: ChatRequest,
-    user: dict = Depends(verify_firebase_token),
+    user: dict = Depends(with_rate_limit("chat")),
 ):
     """
     Accepts a user message and returns a streaming SSE response.

routes/consultation.py

@@ -17,7 +17,7 @@ from datetime import datetime
 from fastapi import APIRouter, HTTPException, Depends
 from pydantic import BaseModel
 from firebase_admin import firestore
-from auth import verify_firebase_token
+from utils.rate_limiter import with_rate_limit
 from utils.groq_client import call_groq_json, HEAVY_MODEL
 from utils.pinecone_client import query_book_context
 
@@ -52,7 +52,7 @@ def _read_profile(user_id: str, business_id: str) -> dict:
 @router.post("/start")
 def start_consultation(
     body: StartRequest,
-    user: dict = Depends(verify_firebase_token),
+    user: dict = Depends(with_rate_limit("generation")),
 ):
     """
     Reads the entrepreneur's business profile and generates a warm, structured
@@ -118,7 +118,7 @@ Return JSON:
 @router.post("/report")
 def generate_report(
     body: ReportRequest,
-    user: dict = Depends(verify_firebase_token),
+    user: dict = Depends(with_rate_limit("generation")),
 ):
     """
     Takes the full session transcript and generates a structured consultation

routes/documents.py

@@ -17,7 +17,7 @@ import json
 from fastapi import APIRouter, HTTPException, Depends
 from pydantic import BaseModel
 from firebase_admin import firestore
-from auth import verify_firebase_token
+from utils.rate_limiter import with_rate_limit
 from utils.groq_client import call_groq_json, HEAVY_MODEL
 from utils.pinecone_client import query_book_context
 
@@ -137,7 +137,7 @@ Generate a 7-slide Pitch Deck. Return JSON where each key is a slide:
 @router.post("/generate-content")
 def generate_document_content(
     body: GenerateDocRequest,
-    user: dict = Depends(verify_firebase_token),
+    user: dict = Depends(with_rate_limit("generation")),
 ):
     """
     Generates AI content for Business Plan or Pitch Deck.

routes/planning.py

@@ -13,7 +13,7 @@ from datetime import datetime, timedelta
 from fastapi import APIRouter, HTTPException, Depends
 from pydantic import BaseModel
 from firebase_admin import firestore
-from auth import verify_firebase_token
+from utils.rate_limiter import with_rate_limit
 from utils.groq_client import call_groq_json, HEAVY_MODEL
 from utils.pinecone_client import query_book_context
 
@@ -47,7 +47,7 @@ def _read_context(user_id: str, business_id: str) -> dict:
 @router.post("/suggest")
 def suggest_planning_items(
     body: SuggestRequest,
-    user: dict = Depends(verify_firebase_token),
+    user: dict = Depends(with_rate_limit("generation")),
 ):
     if body.type not in ("tasks", "milestones"):
         raise HTTPException(status_code=400, detail="type must be 'tasks' or 'milestones'")

routes/transcribe.py

@@ -1,5 +1,5 @@
 from fastapi import APIRouter, UploadFile, File, Depends, HTTPException
-from auth import verify_firebase_token
+from utils.rate_limiter import with_rate_limit
 from utils.groq_client import call_groq_transcribe
 
 router = APIRouter()
@@ -15,7 +15,7 @@ MAX_AUDIO_BYTES = 25 * 1024 * 1024  # 25 MB — Groq Whisper limit
 @router.post("/transcribe")
 async def transcribe_audio(
     audio: UploadFile = File(...),
-    user: dict = Depends(verify_firebase_token),
+    user: dict = Depends(with_rate_limit("transcription")),
 ):
     """
     Accepts a browser-recorded audio blob, sends it to Groq Whisper,

tests/test_account.py

@@ -0,0 +1,91 @@
+"""
+Unit tests for routes/account.py's self-delete cascade.
+
+Scope: verifies delete_all_user_data's Firestore traversal logic (every business's
+subcollections, xpHistory, the root doc) using a fake Firestore client, per
+docs/qa/test-strategy.md's unit layer. The actual Firebase Auth deletion
+(fb_auth.delete_user) and the FastAPI route wiring are integration-level concerns,
+not covered here.
+"""
+from unittest.mock import MagicMock
+from routes.account import delete_all_user_data
+
+
+def _make_fake_db():
+    """
+    Builds a fake Firestore client deep enough to exercise delete_all_user_data:
+    one business with two subcollections each holding one doc, plus one
+    xpHistory entry. Returns (db, deleted_refs) where deleted_refs collects
+    every .delete() call made, in call order.
+    """
+    deleted = []
+
+    def make_doc(name):
+        doc = MagicMock(name=f"doc:{name}")
+        doc.reference = MagicMock(name=f"ref:{name}")
+        doc.reference.delete = MagicMock(side_effect=lambda n=name: deleted.append(n))
+        return doc
+
+    biz_doc = make_doc("business:biz1")
+
+    def sub_collection(name):
+        coll = MagicMock(name=f"collection:{name}")
+        coll.stream = MagicMock(return_value=iter([make_doc(f"{name}:item1")]))
+        return coll
+
+    biz_doc.reference.collection = MagicMock(side_effect=sub_collection)
+
+    businesses_collection = MagicMock(name="collection:businesses")
+    businesses_collection.stream = MagicMock(return_value=iter([biz_doc]))
+
+    xp_history_collection = MagicMock(name="collection:xpHistory")
+    xp_history_collection.stream = MagicMock(return_value=iter([make_doc("xpHistory:entry1")]))
+
+    user_ref = MagicMock(name="ref:user_data/uid")
+    user_ref.delete = MagicMock(side_effect=lambda: deleted.append("user_data/uid"))
+
+    def user_ref_collection(name):
+        return {"businesses": businesses_collection, "xpHistory": xp_history_collection}[name]
+
+    user_ref.collection = MagicMock(side_effect=user_ref_collection)
+
+    user_data_collection = MagicMock(name="collection:user_data")
+    user_data_collection.document = MagicMock(return_value=user_ref)
+
+    db = MagicMock(name="firestore_client")
+    db.collection = MagicMock(return_value=user_data_collection)
+
+    return db, deleted
+
+
+def test_deletes_every_business_subcollection_doc_and_the_business_itself(monkeypatch):
+    db, deleted = _make_fake_db()
+    monkeypatch.setattr("routes.account.firestore.client", lambda: db)
+
+    delete_all_user_data("some-uid")
+
+    # Every one of the 7 known subcollections was consulted for the business...
+    biz_doc = db.collection().document().collection("businesses").stream.return_value
+    # ...and each subcollection's one doc, plus the business doc itself, got deleted.
+    assert "bff:item1" in deleted
+    assert "documents:item1" in deleted
+    assert "team:item1" in deleted
+    assert "business:biz1" in deleted
+
+
+def test_deletes_xp_history_entries(monkeypatch):
+    db, deleted = _make_fake_db()
+    monkeypatch.setattr("routes.account.firestore.client", lambda: db)
+
+    delete_all_user_data("some-uid")
+
+    assert "xpHistory:entry1" in deleted
+
+
+def test_deletes_the_root_user_doc_last(monkeypatch):
+    db, deleted = _make_fake_db()
+    monkeypatch.setattr("routes.account.firestore.client", lambda: db)
+
+    delete_all_user_data("some-uid")
+
+    assert deleted[-1] == "user_data/uid"

tests/test_rate_limiter.py

@@ -0,0 +1,78 @@
+"""
+Unit tests for utils/rate_limiter.py's pure counting/enforcement logic.
+
+Scope: enforce_rate_limit() itself (fixed-window counting, per-tier limits,
+429 on breach). The with_rate_limit() FastAPI dependency composition and the
+Firestore violation-logging side effect are thin wrappers around this and are
+not separately unit-tested (per docs/qa/test-strategy.md, the FastAPI/
+Firestore integration belongs at the integration layer, not here).
+"""
+import time
+import pytest
+from fastapi import HTTPException
+import utils.rate_limiter as rl
+
+
+@pytest.fixture(autouse=True)
+def reset_limiter_state(monkeypatch):
+    # Each test gets a clean set of counters and a violation logger that
+    # never touches Firestore (no app is initialized in this test process).
+    monkeypatch.setattr(rl, "_counters", rl.defaultdict(rl._Window))
+    monkeypatch.setattr(rl, "_violation_counts", rl.defaultdict(int))
+    monkeypatch.setattr(rl, "_log_violation", lambda *a, **k: None)
+
+
+def test_allows_requests_within_the_limit():
+    for _ in range(8):
+        rl.enforce_rate_limit("uid-1", "generation")  # 8/hour is the limit — must not raise
+
+
+def test_blocks_the_request_that_exceeds_the_limit():
+    for _ in range(8):
+        rl.enforce_rate_limit("uid-1", "generation")
+    with pytest.raises(HTTPException) as exc_info:
+        rl.enforce_rate_limit("uid-1", "generation")
+    assert exc_info.value.status_code == 429
+
+
+def test_counters_are_isolated_per_uid():
+    for _ in range(8):
+        rl.enforce_rate_limit("uid-1", "generation")
+    # A different uid must not be affected by uid-1 exhausting its limit.
+    rl.enforce_rate_limit("uid-2", "generation")
+
+
+def test_counters_are_isolated_per_tier():
+    for _ in range(8):
+        rl.enforce_rate_limit("uid-1", "generation")
+    # The same uid hitting a different tier must not be blocked by "generation".
+    rl.enforce_rate_limit("uid-1", "chat")
+
+
+def test_a_tier_with_multiple_windows_enforces_the_tighter_one_first():
+    # "chat" is 10/minute and 200/day -- the per-minute window binds first.
+    for _ in range(10):
+        rl.enforce_rate_limit("uid-1", "chat")
+    with pytest.raises(HTTPException) as exc_info:
+        rl.enforce_rate_limit("uid-1", "chat")
+    assert exc_info.value.status_code == 429
+    assert "minute" in exc_info.value.detail
+
+
+def test_window_resets_after_its_period_elapses(monkeypatch):
+    fake_now = [1_000_000.0]
+    monkeypatch.setattr(rl.time, "time", lambda: fake_now[0])
+
+    for _ in range(8):
+        rl.enforce_rate_limit("uid-1", "generation")
+    with pytest.raises(HTTPException):
+        rl.enforce_rate_limit("uid-1", "generation")
+
+    # Jump past the 1-hour window.
+    fake_now[0] += 3600 + 1
+    rl.enforce_rate_limit("uid-1", "generation")  # must not raise — window reset
+
+
+def test_unknown_tier_raises_a_programmer_error_not_a_silent_pass():
+    with pytest.raises(ValueError):
+        rl.enforce_rate_limit("uid-1", "not-a-real-tier")

utils/rate_limiter.py

@@ -0,0 +1,106 @@
+"""
+Per-UID rate limiter — design settled 2026-09-09 (see
+docs/blueprint/adr/0010-per-uid-in-memory-rate-limiting.md), built 2026-09-25.
+
+Keys by authenticated Firebase UID, not IP — every limited route already
+requires a verified token, and a UID can't be spoofed the way an IP/header
+can. Counters are in-memory, per-process: safe from client/devtools
+tampering by construction, sufficient for the current single-container
+Hugging Face Space deployment, and reset on redeploy. If this ever needs to
+survive across multiple replicas, move the counters into Firestore/Redis —
+the enforce_rate_limit() call site wouldn't need to change.
+"""
+
+import time
+import threading
+from collections import defaultdict
+from fastapi import Header, HTTPException
+from firebase_admin import firestore
+from auth import verify_firebase_token
+
+# (label, limit, period_seconds) per tier. Tiers are named by cost, not by
+# route, so multiple routes can share one (see routes/*.py's with_rate_limit
+# calls for which tier each route uses).
+TIERS: dict[str, list[tuple[str, int, int]]] = {
+    "chat":           [("minute", 10, 60), ("day", 200, 86400)],
+    "generation":     [("hour", 8, 3600), ("day", 30, 86400)],
+    "transcription":  [("day", 20, 86400)],
+}
+
+
+class _Window:
+    __slots__ = ("count", "reset_at")
+
+    def __init__(self) -> None:
+        self.count = 0
+        self.reset_at = 0.0
+
+
+_lock = threading.Lock()
+_counters: dict[tuple[str, str, str], _Window] = defaultdict(_Window)
+# Consecutive-violation count per UID, purely for the "log repeat offenders"
+# requirement — never used to make an enforcement decision itself.
+_violation_counts: dict[str, int] = defaultdict(int)
+
+
+def _log_violation(uid: str, tier: str, label: str, count: int, limit: int) -> None:
+    _violation_counts[uid] += 1
+    print(
+        f"[rate-limit] uid={uid} tier={tier} window={label} "
+        f"count={count}/{limit} (consecutive violations: {_violation_counts[uid]})"
+    )
+    # Best-effort — a Firestore write failing must never break enforcement itself.
+    try:
+        firestore.client().collection("rate_limit_violations").add({
+            "uid": uid,
+            "tier": tier,
+            "window": label,
+            "count": count,
+            "limit": limit,
+            "consecutiveViolations": _violation_counts[uid],
+            "at": firestore.SERVER_TIMESTAMP,
+        })
+    except Exception:
+        pass
+
+
+def enforce_rate_limit(uid: str, tier: str) -> None:
+    """Raises HTTPException(429) if uid has exceeded any of tier's limits."""
+    if tier not in TIERS:
+        raise ValueError(f"Unknown rate limit tier: {tier!r}")
+
+    now = time.time()
+    with _lock:
+        for label, limit, period in TIERS[tier]:
+            window = _counters[(uid, tier, label)]
+            if now >= window.reset_at:
+                window.count = 0
+                window.reset_at = now + period
+            window.count += 1
+
+            if window.count > limit:
+                retry_after = max(1, int(window.reset_at - now))
+                _log_violation(uid, tier, label, window.count, limit)
+                raise HTTPException(
+                    status_code=429,
+                    detail=(
+                        f"You've hit the {label}ly limit for this action "
+                        f"({limit} per {label}). Try again in {retry_after} seconds."
+                    ),
+                    headers={"Retry-After": str(retry_after)},
+                )
+
+
+def with_rate_limit(tier: str):
+    """
+    FastAPI dependency: verifies the caller's token AND enforces `tier`'s rate
+    limit in one pass. Use this in place of `Depends(verify_firebase_token)`
+    on any route that should be limited — it calls verify_firebase_token
+    itself rather than composing as a second dependency, so the token is only
+    verified once per request.
+    """
+    async def dependency(authorization: str = Header(...)) -> dict:
+        user = await verify_firebase_token(authorization)
+        enforce_rate_limit(user["uid"], tier)
+        return user
+    return dependency