H

.gitignore

@@ -18,3 +18,8 @@ __pycache__/
 Thumbs.db
 .vscode/
 .idea/
+
+# No local file storage — defensive ignore in case anything slips in
+challenge_files/
+/tmp/
+/tempfiles/

README.md

@@ -1,10 +1,164 @@
----
-title: CyberArena
-emoji: 🏆
-colorFrom: yellow
-colorTo: yellow
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# CyberArena — Backend
+
+> FastAPI backend for the CyberArena cybersecurity training platform.
+> Single source of truth: this directory. The old `Apex/backend/` has
+> been removed.
+
+## Quick start
+
+```bash
+cd CyberArena
+pip install -r requirements.txt
+python main.py        # serves on http://localhost:8090
+```
+
+The server loads `.env` automatically from this folder.
+
+## Project layout
+
+```
+CyberArena/
+├── main.py                        ← 5-line uvicorn entry
+├── requirements.txt
+├── Dockerfile
+├── start.cmd
+│
+├── app/                           ← all real code
+│   ├── main.py                    ← FastAPI app, middleware, startup
+│   ├── types.py                   ← Pydantic request models
+│   │
+│   ├── core/                      ← constants + pure helpers (no I/O)
+│   │   ├── config.py              ← env-loaded handles (Supabase, AI URLs, keys)
+│   │   ├── constants.py           ← topic catalog, fallback HTML, cert config
+│   │   ├── security.py            ← normalize_vuln_key, ip/ioc/time matchers
+│   │   ├── text.py                ← parse_json_safe (LLM JSON parser)
+│   │   └── module_router.py       ← module → challenge_type dispatcher
+│   │
+│   ├── services/                  ← business logic / I/O
+│   │   ├── supabase_service.py    ← PostgREST client (CRUD on pool tables)
+│   │   ├── challenge_loader.py    ← row → TrainingData mappers (per type)
+│   │   ├── scenario_service.py    ← Groq scenario + challenge generation
+│   │   ├── evaluator.py           ← /evaluate handlers (5 types)
+│   │   ├── completion_service.py  ← user_completions idempotent tracker
+│   │   ├── certificate_service.py ← PDF build + cert issue/verify/download
+│   │   └── file_storage.py        ← write downloadable files to disk
+│   │
+│   ├── generators/                ← per-type AI pool generators
+│   │   ├── __init__.py            ← REGISTRY: list of (slug, module, teams)
+│   │   ├── crypto.py              ← owns encryption_challenges
+│   │   ├── web.py                 ← owns web_exploitation_challenges
+│   │   ├── code_fixing.py         ← owns code_fixing_challenges
+│   │   ├── log_analysis.py        ← owns log_analysis_challenges
+│   │   └── vulnerability_hunter.py ← owns vulnerability_hunter_challenges
+│   │
+│   ├── sandbox/                   ← in-process OS simulator sandbox
+│   │   ├── workdir.py             ← per-challenge tempdir + safe_join
+│   │   ├── tools.py               ← built-in cat/ls/sha256sum/base64/…
+│   │   └── terminal.py            ← shlex parse + whitelist subprocess run
+│   │
+│   └── api/                       ← FastAPI routers (HTTP shell only)
+│       ├── auth.py                ← /api/auth
+│       ├── xp.py                  ← /api/xp
+│       ├── leaderboard.py         ← /api/leaderboard
+│       ├── certificates.py        ← /api/certificates*
+│       ├── training.py            ← /api/training/*
+│       ├── terminal.py            ← /api/training/terminal*
+│       └── onevone.py             ← /api/onevone/* (head-to-head matches)
+│
+├── db/                            ← all database concerns
+│   ├── schema/                    ← numbered, idempotent SQL migrations
+│   │   ├── 000_extensions.sql
+│   │   ├── 001_users.sql
+│   │   ├── 002_encryption_challenges.sql
+│   │   ├── 003_web_exploitation_challenges.sql
+│   │   ├── 004_code_fixing_challenges.sql
+│   │   ├── 005_log_analysis_challenges.sql
+│   │   ├── 006_vulnerability_hunter_challenges.sql
+│   │   ├── 007_onevone.sql
+│   │   ├── 008_certificates.sql
+│   │   └── 009_user_completions.sql
+│   ├── seed/                      ← per-type example JSON (template)
+│   │   ├── README.md
+│   │   ├── crypto.example.json
+│   │   ├── web.example.json
+│   │   ├── code_fixing.example.json
+│   │   ├── log_analysis.example.json
+│   │   └── vulnerability_hunter.example.json
+│   ├── apply.py                   ← apply every schema/*.sql in order
+│   └── README.md
+│
+├── scripts/                       ← ops utilities
+│   ├── check_state.py             ← one-page DB health report
+│   └── seed_pools.py              ← pool size + status (read-only by default)
+│
+├── .env                           ← secrets (never commit)
+└── README.md
+
+> **No local file storage.** AI-generated challenge files are uploaded
+> to the `challenge-files` Supabase Storage bucket (see
+> `db/schema/010_challenge_files_bucket.sql`) and the public URL is
+> returned in the training payload. The backend never writes to its
+> own disk.
+```
+
+## API surface
+
+The FastAPI app exposes **28 routes** under `/api/`. The full list
+lives in `app/main.py`; the most important are:
+
+| Method | Path                                | Notes |
+|--------|-------------------------------------|-------|
+| POST   | `/api/auth`                         | proxied to Supabase `apex-auth` edge function |
+| POST   | `/api/xp`                           | proxied to Supabase `apex-xp` edge function |
+| GET    | `/api/leaderboard`                  | top users by XP |
+| GET    | `/api/training/list`                | dashboard cards |
+| POST   | `/api/training/generate`            | hydrate cached scenario into a full challenge |
+| POST   | `/api/training/evaluate`            | legacy red+blue AI evaluator |
+| POST   | `/api/training/evaluate-web`        | 3-layer web exploitation validator |
+| POST   | `/api/training/evaluate-code-fix`   | AI code-fix grader |
+| POST   | `/api/training/evaluate-log-analysis` | 4-field exact match + Mistral feedback |
+| POST   | `/api/training/evaluate-vulnerability-hunter` | exact canonical-key match |
+| POST   | `/api/training/terminal*`           | OS simulator sandbox |
+| POST   | `/api/certificates`                 | list / issue |
+| GET    | `/api/certificates/{id}/pdf`        | streamed PDF |
+| GET    | `/api/certificates/verify/{code}`   | public QR landing |
+| GET    | `/api/certificates/progress`        | (completions, required) |
+| POST   | `/api/onevone/rooms`                | 1v1 mode (see `app/api/onevone.py`) |
+
+## Pool architecture
+
+Each challenge type owns its own table + its own generator. The
+orchestrator in `app/main.py::populate_pool_background` walks
+`app.generators.REGISTRY` and starts one watcher per (type, team).
+
+Pool model: `POOL_TARGET / POOL_THRESHOLD / POOL_BATCH` are module
+constants inside each generator. The watcher refills the table
+when the count drops to `POOL_THRESHOLD` and inserts `POOL_BATCH` new
+rows in parallel via `asyncio.gather`.
+
+See `../AGENTS.md` "Pool Architecture" for the full contract.
+
+## Database
+
+Apply the migrations to Supabase with:
+
+```bash
+python db/apply.py          # needs SUPABASE_SERVICE_KEY in .env
+```
+
+Each `.sql` file is idempotent (`CREATE … IF NOT EXISTS`, `DROP
+POLICY IF EXISTS + CREATE`). See `db/README.md` for details.
+
+## Running tests
+
+There is no formal test suite yet. Use:
+
+```bash
+python -c "from app.main import app; print(len(app.routes), 'routes')"
+python scripts/check_state.py     # requires SUPABASE_URL
+```
+
+## Deployment
+
+The provided `Dockerfile` pins `python:3.11-slim` and starts the
+server on `PORT` (default 7860, matches Hugging Face Spaces).

app/__init__.py

@@ -0,0 +1,15 @@
+"""CyberArena backend package.
+
+This package organises the FastAPI backend into focused subpackages:
+
+  app.core          → constants, helpers (no I/O)
+  app.services      → business logic that talks to Supabase / AI providers
+  app.generators    → per-challenge-type AI pool generators
+  app.sandbox       → in-process terminal sandbox for the OS simulator
+  app.api           → FastAPI routers mounted under /api/...
+
+The actual FastAPI ``app`` is built in :mod:`app.main` and re-exported as
+``app.main:app`` so the top-level ``main.py`` stays a 5-line entry.
+"""
+
+__all__ = ["main"]

app/_env.py

@@ -0,0 +1,172 @@
+"""Centralised .env loader.
+
+This module is imported **first** by every other module that touches
+``os.environ`` (currently :mod:`app.main` and :mod:`app.core.config`).
+It searches a small list of candidate locations for the project's
+``.env`` file and loads it via :func:`dotenv.load_dotenv`.
+
+**Search order** (first hit wins):
+
+1. ``./.env`` (process working directory)
+2. ``../.env`` (one level up — useful when running from ``app/``)
+3. ``<this_file>/../.env`` (sibling of the ``app/`` package — the
+   canonical location: ``CyberArena/.env``)
+4. ``<this_file>/.env`` (inside the ``app/`` package — auto-created
+   copies; we tolerate them but don't prefer them)
+
+The function prints a single line of status to stdout so the operator
+knows exactly which file was used, and which critical variables were
+actually picked up.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Iterable, Optional
+
+
+# --------------------------------------------------------------------------- #
+#  Internal helpers                                                           #
+# --------------------------------------------------------------------------- #
+
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+def _is_loaded_marker_set() -> bool:
+    """We use a sentinel env var so we never load twice."""
+    return os.environ.get("_APEX_ENV_LOADED") == "1"
+
+
+def _set_loaded_marker() -> None:
+    os.environ["_APEX_ENV_LOADED"] = "1"
+
+
+def _mask(value: str) -> str:
+    """Return a masked version of a secret suitable for printing."""
+    if not value:
+        return "<MISSING>"
+    if len(value) <= 8:
+        return "***"
+    return f"{value[:4]}…{value[-4:]} (len={len(value)})"
+
+
+def _candidate_paths() -> Iterable[Path]:
+    """Yield the candidate .env locations, in priority order."""
+    here = Path(__file__).resolve()
+    app_dir = here.parent
+    backend_dir = app_dir.parent  # CyberArena/
+    cwd = Path.cwd()
+
+    seen: set[Path] = set()
+
+    for path in (
+        cwd / ".env",
+        cwd.parent / ".env",  # one above cwd (in case you ran from app/)
+        backend_dir / ".env",  # the canonical location
+        app_dir / ".env",  # the stray copy inside the package
+    ):
+        try:
+            resolved = path.resolve()
+        except FileNotFoundError:
+            continue
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        yield path
+
+
+def _find_env() -> Optional[Path]:
+    """Return the first existing .env in the candidate list."""
+    for path in _candidate_paths():
+        if path.is_file():
+            return path
+    return None
+
+
+# --------------------------------------------------------------------------- #
+#  Public entry point                                                         #
+# --------------------------------------------------------------------------- #
+
+
+def load_app_env(verbose: bool = True) -> Optional[Path]:
+    """Load the CyberArena ``.env`` file into ``os.environ``.
+
+    Idempotent: a second call is a no-op.  Returns the path that was
+    loaded, or ``None`` if no file was found.
+    """
+    if _is_loaded_marker_set():
+        return None
+
+    from dotenv import load_dotenv  # local import — cheap, no I/O
+
+    env_path = _find_env()
+    if env_path is None:
+        if verbose:
+            print(
+                "[env] WARNING: no .env file found. Searched:",
+                file=sys.stderr,
+            )
+            for p in _candidate_paths():
+                print(f"        - {p}", file=sys.stderr)
+            print(
+                "[env] Create CyberArena/.env with SUPABASE_URL / "
+                "SUPABASE_ANON_KEY / CLOUDFLARE_* / GROQ_API_KEY.",
+                file=sys.stderr,
+            )
+        _set_loaded_marker()
+        return None
+
+    # ``override=False`` so process env wins over .env when both are set
+    # (e.g. secrets injected by Hugging Face Spaces / Docker).
+    load_dotenv(dotenv_path=str(env_path), override=False, encoding="utf-8")
+    _set_loaded_marker()
+
+    if verbose:
+        supabase_url = os.environ.get("SUPABASE_URL", "")
+        supabase_key = os.environ.get("SUPABASE_ANON_KEY", "")
+        cf_token = os.environ.get("CLOUDFLARE_API_TOKEN", "")
+        groq_key = os.environ.get("GROQ_API_KEY", "")
+        nvidia_key = os.environ.get("NVIDIA_API_KEY", "")
+        mistral_key = os.environ.get("MISTRAL_API_KEY", "")
+
+        print(f"[env] Loaded: {env_path}")
+        print(
+            f"[env]   SUPABASE_URL        = {supabase_url or '<MISSING>'}",
+        )
+        print(
+            f"[env]   SUPABASE_ANON_KEY   = {_mask(supabase_key)}",
+        )
+        print(
+            f"[env]   CLOUDFLARE_API_TOKEN= {_mask(cf_token)}",
+        )
+        print(
+            f"[env]   GROQ_API_KEY        = {_mask(groq_key)}",
+        )
+        print(
+            f"[env]   NVIDIA_API_KEY      = {_mask(nvidia_key)}",
+        )
+        print(
+            f"[env]   MISTRAL_API_KEY     = {_mask(mistral_key)}",
+        )
+
+    return env_path
+
+
+def assert_critical_env(*keys: str) -> None:
+    """Raise :class:`RuntimeError` if any of ``keys`` is missing.
+
+    Use it right after :func:`load_app_env` to fail loudly instead of
+    later with a cryptic ``KeyError`` deep in an httpx call.
+    """
+    missing = [k for k in keys if not os.environ.get(k)]
+    if missing:
+        raise RuntimeError(
+            "Missing required environment variables: "
+            + ", ".join(missing)
+            + ".\nMake sure CyberArena/.env is present and contains them."
+        )
+
+
+__all__ = ["load_app_env", "assert_critical_env"]

app/api/__init__.py

@@ -0,0 +1,24 @@
+"""FastAPI routers grouped by concern.
+
+Each module in this package defines a single ``router = APIRouter(...)``
+and exposes the route handlers. The actual app lives in
+:mod:`app.main` and mounts every router with ``app.include_router(...)``.
+"""
+
+from . import auth
+from . import xp
+from . import leaderboard
+from . import training
+from . import terminal
+from . import certificates
+from . import onevone
+
+__all__ = [
+    "auth",
+    "xp",
+    "leaderboard",
+    "training",
+    "terminal",
+    "certificates",
+    "onevone",
+]

app/api/auth.py

@@ -0,0 +1,23 @@
+"""``/api/auth`` — proxy to the Supabase ``apex-auth`` edge function."""
+
+import httpx
+from fastapi import APIRouter, HTTPException
+
+from app.core.config import SUPABASE_EDGE_URL
+from app.types import AuthRequest
+
+
+router = APIRouter()
+
+
+@router.post("/api/auth")
+async def handle_auth(req: AuthRequest):
+    async with httpx.AsyncClient(timeout=30) as client:
+        resp = await client.post(
+            f"{SUPABASE_EDGE_URL}/apex-auth",
+            json={"action": req.action, "email": req.email, "password": req.password, "name": req.name},
+        )
+    data = resp.json()
+    if resp.status_code != 200:
+        raise HTTPException(status_code=resp.status_code, detail=data.get("error", "Auth failed"))
+    return data

app/api/certificates.py

@@ -0,0 +1,34 @@
+"""``/api/certificates`` — issuance, download, verify, progress."""
+
+from fastapi import APIRouter
+
+from app.types import CertificateRequest
+from app.services.certificate_service import (
+    handle_certificates,
+    download_certificate_pdf,
+    verify_certificate,
+    cert_progress,
+)
+
+
+router = APIRouter()
+
+
+@router.post("/api/certificates")
+async def post_certificates(req: CertificateRequest):
+    return await handle_certificates(req)
+
+
+@router.get("/api/certificates/{cert_id}/pdf")
+async def get_certificate_pdf(cert_id: str, lang: str = "en"):
+    return await download_certificate_pdf(cert_id, lang)
+
+
+@router.get("/api/certificates/verify/{verify_code}")
+async def get_verify(verify_code: str):
+    return await verify_certificate(verify_code)
+
+
+@router.get("/api/certificates/progress")
+async def get_progress(user_id: str, category: str):
+    return await cert_progress(user_id, category)

app/api/leaderboard.py

@@ -0,0 +1,48 @@
+"""``/api/leaderboard`` — top users ranked by XP."""
+
+import httpx
+from fastapi import APIRouter
+
+from app.core.config import SUPABASE_URL, SUPABASE_ANON_KEY
+from app.services.supabase_service import supabase_headers
+
+
+router = APIRouter()
+
+
+@router.get("/api/leaderboard")
+async def get_leaderboard(limit: int = 50):
+    """Fetch top users ranked by XP from the public ``leaderboard`` view."""
+    headers = {
+        "apikey": SUPABASE_ANON_KEY,
+        "Authorization": f"Bearer {SUPABASE_ANON_KEY}",
+        "Content-Type": "application/json",
+    }
+    safe_limit = max(1, min(limit, 100))
+    url = (
+        f"{SUPABASE_URL}/rest/v1/leaderboard"
+        f"?select=id,name,xp,completed_trainings"
+        f"&order=xp.desc"
+        f"&limit={safe_limit}"
+    )
+    try:
+        async with httpx.AsyncClient(timeout=20) as client:
+            resp = await client.get(url, headers=headers)
+        if resp.status_code != 200:
+            print(f"Leaderboard fetch error: {resp.status_code} {resp.text}")
+            return {"users": [], "total": 0}
+        rows = resp.json()
+    except Exception as e:
+        print(f"Leaderboard exception: {e}")
+        return {"users": [], "total": 0}
+
+    cleaned = []
+    for i, row in enumerate(rows, start=1):
+        cleaned.append({
+            "rank": i,
+            "id": row.get("id"),
+            "name": row.get("name") or "مشغل",
+            "xp": int(row.get("xp") or 0),
+            "completed_trainings": int(row.get("completed_trainings") or 0),
+        })
+    return {"users": cleaned, "total": len(cleaned)}

onevone_router.py → app/api/onevone.py

@@ -252,14 +252,18 @@ async def _ai_check_blue_answer(challenge_row: dict, challenge_type: str, payloa
             return False
         # Reuse the exact same AI evaluator that /api/training/evaluate-code-fix
         # uses, so the 1v1 server agrees with the local TrainingSession eval.
-        from main import _ai_evaluate_code_fix
-        evaluation = await _ai_evaluate_code_fix(str(challenge_row["id"]), fixed, "blue")
+        from app.services.evaluator import ai_evaluate_code_fix
+        evaluation = await ai_evaluate_code_fix(str(challenge_row["id"]), fixed, "blue")
         return bool(evaluation.get("secured"))
 
     if challenge_type == "log-analysis":
-        # inline re-implementation of the 4-field match (same logic as main.py)
-        from main import (
-            _normalize_str, _ip_matches, _timestamp_close, _ioc_matches
+        # inline re-implementation of the 4-field match (same logic as
+        # app.services.evaluator.evaluate_log_analysis)
+        from app.core.security import (
+            normalize_str as _normalize_str,
+            ip_matches as _ip_matches,
+            timestamp_close as _timestamp_close,
+            ioc_matches as _ioc_matches,
         )
         expected_attack = _normalize_str(challenge_row.get("expected_attack_type", ""))
         expected_ip = challenge_row.get("expected_attacker_ip", "") or ""
@@ -277,9 +281,10 @@ async def _ai_check_blue_answer(challenge_row: dict, challenge_type: str, payloa
         return correct >= 3  # 3 of 4 — same threshold as main.py
 
     if challenge_type == "vulnerability-hunter":
-        # deterministic key match — same logic as main.py::evaluate_vuln_hunter
-        from main import _normalize_vuln_key
-        expected = _normalize_vuln_key(challenge_row.get("vulnerability_type", ""))
+        # deterministic key match — same logic as
+        # app.services.evaluator.evaluate_vuln_hunter
+        from app.core.security import normalize_vuln_key
+        expected = normalize_vuln_key(challenge_row.get("vulnerability_type", ""))
         user = _normalize_vuln_key((payload or {}).get("vulnerabilityType", ""))
         return bool(expected) and (user == expected)
 
@@ -726,13 +731,13 @@ async def get_match_challenge(match_id: str, userId: str):
     ps = await _sb_select("onevone_players", f"room_id=eq.{match['room_id']}&select=user_id")
     if not any(str(p["user_id"]) == str(userId) for p in ps):
         raise HTTPException(status_code=403, detail="لست لاعباً في هذه المباراة")
-    # delegate to the existing mapper in main.py
-    from main import (
-        _map_encryption_row_to_training,
-        _map_webex_row_to_training,
-        _map_code_fixing_row_to_training,
-        _map_log_analysis_row_to_training,
-        _map_vuln_hunter_row_to_training,
+    # delegate to the existing mapper in app.services.challenge_loader
+    from app.services.challenge_loader import (
+        map_encryption_row_to_training as _map_encryption_row_to_training,
+        map_webex_row_to_training as _map_webex_row_to_training,
+        map_code_fixing_row_to_training as _map_code_fixing_row_to_training,
+        map_log_analysis_row_to_training as _map_log_analysis_row_to_training,
+        map_vuln_hunter_row_to_training as _map_vuln_hunter_row_to_training,
     )
     row = await _load_challenge_row(match["challenge_id"], match["challenge_type"])
     # team_role on the row is the source of truth for evaluator side

app/api/terminal.py

@@ -0,0 +1,79 @@
+"""``/api/training/terminal*`` — the in-process OS simulator endpoints."""
+
+import os
+
+from fastapi import APIRouter
+
+from app.sandbox.terminal import run_terminal_command
+from app.sandbox.workdir import get_or_create_workdir, safe_join
+from app.types import (
+    TerminalRequest,
+    TerminalWriteRequest,
+    TerminalListRequest,
+)
+
+
+router = APIRouter()
+
+
+@router.post("/api/training/terminal")
+async def post_terminal(req: TerminalRequest):
+    """Execute a terminal command in the challenge's sandbox for real."""
+    team_role = req.teamRole or "red"
+    return await run_terminal_command(team_role, req.challengeId, req.command)
+
+
+@router.post("/api/training/terminal/write")
+async def post_terminal_write(req: TerminalWriteRequest):
+    """Write/edit a file inside the sandbox workdir (path-traversal safe)."""
+    team_role = req.teamRole or "red"
+    challenge_id = req.challengeId
+    if not challenge_id:
+        return {"ok": False, "error": "❌ challengeId مفقود"}
+    if not req.filename:
+        return {"ok": False, "error": "❌ اسم الملف مفقود"}
+    if len(req.content) > 200_000:
+        return {"ok": False, "error": "❌ الملف كبير جداً (الحد 200KB)"}
+
+    workdir, _row = await get_or_create_workdir(team_role, challenge_id)
+    try:
+        target = safe_join(workdir, req.filename)
+    except ValueError as e:
+        return {"ok": False, "error": f"❌ مسار غير مسموح: {e}"}
+
+    try:
+        os.makedirs(os.path.dirname(target) or workdir, exist_ok=True)
+        with open(target, "w", encoding="utf-8", newline="\n") as f:
+            f.write(req.content)
+        return {"ok": True, "path": os.path.relpath(target, workdir).replace("\\", "/")}
+    except Exception as e:
+        return {"ok": False, "error": f"❌ تعذّر الحفظ: {e}"}
+
+
+@router.post("/api/training/terminal/list")
+async def post_terminal_list(req: TerminalListRequest):
+    """List files currently in the sandbox workdir (for the file explorer)."""
+    team_role = req.teamRole or "red"
+    challenge_id = req.challengeId
+    if not challenge_id:
+        return {"files": []}
+
+    workdir, _row = await get_or_create_workdir(team_role, challenge_id)
+    files = []
+    try:
+        for name in sorted(os.listdir(workdir)):
+            if name.startswith("."):
+                continue
+            p = os.path.join(workdir, name)
+            if os.path.isfile(p):
+                try:
+                    with open(p, "r", encoding="utf-8", errors="replace") as f:
+                        content = f.read()
+                    if len(content) > 50_000:
+                        content = content[:50_000] + "\n... (truncated)"
+                    files.append({"name": name, "content": content})
+                except Exception:
+                    files.append({"name": name, "content": "(binary file)"})
+    except Exception:
+        pass
+    return {"files": files}

app/api/training.py

@@ -0,0 +1,387 @@
+"""``/api/training/*`` — list, generate, evaluate, solve endpoints.
+
+Per-type generation / mapping logic lives in
+:mod:`app.services.scenario_service` and
+:mod:`app.services.challenge_loader`. Per-type evaluation lives in
+:mod:`app.services.evaluator`. This router is a thin HTTP shell.
+"""
+
+from typing import Optional
+import random
+
+from fastapi import APIRouter, BackgroundTasks, HTTPException
+
+from app.core.constants import CYBER_SECURITY_TOPICS
+from app.core.module_router import challenge_type_for_module
+from app.services.challenge_loader import (
+    map_encryption_row_to_training,
+    map_webex_row_to_training,
+    map_code_fixing_row_to_training,
+    map_log_analysis_row_to_training,
+    map_vuln_hunter_row_to_training,
+)
+from app.services.evaluator import (
+    evaluate_training,
+    evaluate_web_exploitation,
+    evaluate_code_fix,
+    evaluate_log_analysis,
+    evaluate_vuln_hunter,
+)
+from app.services.scenario_service import (
+    attach_scenario_metadata,
+    handle_background_replacement,
+    map_scenario_to_list_item,
+)
+from app.services.supabase_service import (
+    fetch_scenario_by_id,
+    fetch_random_scenario_from_supabase,
+    fetch_all_scenarios_for_type,
+    get_supabase_scenario_count,
+    scenario_table,
+)
+from app.types import (
+    EvaluateRequest,
+    WebEvaluateRequest,
+    TrainingRequest,
+    SolvedRequest,
+    CodeFixEvaluateRequest,
+    LogAnalysisEvaluateRequest,
+    VulnHunterEvaluateRequest,
+)
+
+
+router = APIRouter()
+
+
+# --------------------------------------------------------------------------- #
+#  /api/training/list — dashboard list                                       #
+# --------------------------------------------------------------------------- #
+
+@router.get("/api/training/list")
+async def list_challenges(team_role: str = "blue", difficulty: Optional[str] = None, limit: int = 100):
+    """List cached challenges for a team.
+
+    For each challenge type the team has access to, fetch all rows
+    (capped at ``limit``) and map them to the lightweight list shape
+    the dashboard renders. Blue team gets code-fixing / log-analysis
+    / vulnerability-hunter; red team gets crypto / web.
+
+    Note: the previous implementation called
+    :func:`fetch_random_scenario_from_supabase` with an empty
+    ``module`` argument, which built a ``module=eq.`` PostgREST
+    filter that never matched (modules in the DB are never empty).
+    That made the dashboard report zero challenges even when the pool
+    was full. This version uses
+    :func:`fetch_all_scenarios_for_type` instead.
+    """
+    candidates: list[str] = []
+    if team_role == "blue":
+        candidates = ["code-fixing", "log-analysis", "vulnerability-hunter"]
+    else:
+        candidates = ["crypto", "web"]
+
+    items: list[dict] = []
+    per_type_cap = max(1, limit // max(1, len(candidates)))
+    for ctype in candidates:
+        try:
+            rows = await fetch_all_scenarios_for_type(
+                team_role, challenge_type=ctype, limit=per_type_cap
+            )
+            if not rows:
+                continue
+            for row in rows:
+                row["_challenge_type"] = ctype
+                items.append(map_scenario_to_list_item(row))
+                if len(items) >= limit:
+                    break
+        except Exception as e:
+            print(f"[list_challenges] {ctype}: {e}")
+            continue
+        if len(items) >= limit:
+            break
+
+    return {"items": items, "total": len(items)}
+
+
+# --------------------------------------------------------------------------- #
+#  /api/training/solved — consume one from the pool                            #
+# --------------------------------------------------------------------------- #
+
+@router.post("/api/training/solved")
+async def solve_challenge(req: SolvedRequest, background_tasks: BackgroundTasks):
+    ctype = challenge_type_for_module(req.module or "")
+    background_tasks.add_task(
+        handle_background_replacement,
+        req.scenarioId,
+        req.teamRole or "red",
+        req.module or "",
+        req.path or "web-security",
+        req.category or "web",
+        req.difficulty or "متوسط",
+    )
+    return {"status": "consumed", "challenge_type": ctype}
+
+
+# --------------------------------------------------------------------------- #
+#  /api/training/generate — hydrate a cached scenario into a full challenge   #
+# --------------------------------------------------------------------------- #
+
+@router.post("/api/training/generate")
+async def generate_training(req: TrainingRequest, background_tasks: BackgroundTasks):
+    module = req.module
+    path = req.path
+    category = req.category
+    challenge_id = req.challengeId
+    team_role = req.teamRole or "red"
+
+    if not module or not path or not category:
+        raise HTTPException(status_code=400, detail="module / path / category are required")
+
+    # The ``module`` field on the request is the **challenge type** (one of
+    # the five canonical values) — see AGENTS.md "Challenge Type vs Module".
+    # We use it to (a) look the row up in the right table and (b) pin
+    # training.type to the canonical value.
+    challenge_type = _normalize_challenge_type(module)
+
+    # 1) Try to grab a cached scenario for this (type, team). When
+    # ``challenge_id`` is given we look in every per-type table until
+    # we find the row; otherwise we pick a random row from the table
+    # that matches the requested type.
+    scenario: Optional[dict] = None
+    if challenge_id:
+        scenario = await _fetch_scenario_by_id_typed(
+            team_role, challenge_id, challenge_type
+        )
+    if not scenario:
+        scenario = await _fetch_random_scenario_typed(
+            team_role, challenge_type
+        )
+
+    if not scenario:
+        raise HTTPException(
+            status_code=404,
+            detail=(
+                f"لا يوجد سيناريو في البركة لهذه الوحدة ({module}). "
+                "سيناريو جديد سيُولَّد قريباً."
+            ),
+        )
+
+    # 2) Project the raw DB row straight into the TrainingData shape.
+    #    The row mappers in app.services.challenge_loader are the
+    #    single source of truth for "DB row → front-end payload" — they
+    #    include vulnerable_code / log_url / htmlPreview / etc. for
+    #    each type, so no further AI round-trip is needed.
+    training_data = _project_row_to_training(scenario, team_role, challenge_type)
+
+    # 3) For legacy callers / fronts that still expect a ``type``
+    #    alias and a stable id, run the metadata attach. It is now a
+    #    pure pass-through because the mapper already set every field.
+    training_data = attach_scenario_metadata(
+        training_data, scenario, challenge_type=challenge_type
+    )
+
+    return {"training": training_data}
+
+
+# --------------------------------------------------------------------------- #
+#  Row → TrainingData projection                                              #
+# --------------------------------------------------------------------------- #
+
+_TYPE_TO_MAPPER = {
+    "crypto":               "map_encryption_row_to_training",
+    "web":                  "map_webex_row_to_training",
+    "code-fixing":          "map_code_fixing_row_to_training",
+    "log-analysis":         "map_log_analysis_row_to_training",
+    "vulnerability-hunter": "map_vuln_hunter_row_to_training",
+}
+
+
+def _project_row_to_training(
+    scenario: dict, team_role: str, challenge_type: str
+) -> dict:
+    """Run the per-type mapper against a raw DB row.
+
+    Falls back to a minimal "best-effort" shape when the challenge
+    type is unknown so that the front-end at least gets a
+    ``type``/``id`` pair to render a generic error. This should
+    never fire in practice because the candidate list in
+    ``list_challenges`` only returns the five canonical types.
+    """
+    mapper_name = _TYPE_TO_MAPPER.get(challenge_type)
+    if mapper_name is None:
+        return {
+            "id": str(scenario.get("id", "")),
+            "scenarioId": str(scenario.get("id", "")),
+            "title": scenario.get("title", ""),
+            "story": scenario.get("story", ""),
+            "task": scenario.get("task_outline", ""),
+            "type": challenge_type,
+            "difficulty": scenario.get("difficulty", "متوسط"),
+            "xpReward": scenario.get("xp_reward", 150),
+            "hints": scenario.get("hints") or [],
+        }
+    mapper = globals()[mapper_name]
+    return mapper(scenario, team_role)
+
+
+# --------------------------------------------------------------------------- #
+#  Helpers used only by /api/training/generate                                #
+# --------------------------------------------------------------------------- #
+
+# Canonical challenge types — these are the ONLY values that may appear
+# in ``training["type"]`` and they map 1:1 to a per-type Supabase table.
+_CANONICAL_CHALLENGE_TYPES: dict[str, str] = {
+    "crypto": "crypto",
+    "encryption": "crypto",
+    "web": "web",
+    "code-fixing": "code-fixing",
+    "code_fixing": "code-fixing",
+    "log-analysis": "log-analysis",
+    "log_analysis": "log-analysis",
+    "vulnerability-hunter": "vulnerability-hunter",
+    "vulnerability_hunter": "vulnerability-hunter",
+}
+
+
+def _normalize_challenge_type(module: str) -> str:
+    """Resolve any module alias to its canonical challenge type.
+
+    Unknown values fall through to ``"crypto"`` (the legacy default) so
+    that the red-team code path keeps working. The trainer endpoint
+    never raises on bad input — it logs and best-efforts.
+    """
+    key = (module or "").strip().lower()
+    return _CANONICAL_CHALLENGE_TYPES.get(key, "crypto")
+
+
+def _tables_for_team(team_role: str) -> list[str]:
+    """All per-type tables that can hold a row for ``team_role``.
+
+    Used to look up a row by id without knowing its type up front. The
+    list is short and stable so a sequential scan is fine.
+    """
+    if team_role == "red":
+        return [
+            "encryption_challenges",
+            "web_exploitation_challenges",
+        ]
+    return [
+        "code_fixing_challenges",
+        "log_analysis_challenges",
+        "vulnerability_hunter_challenges",
+    ]
+
+
+async def _fetch_scenario_by_id_typed(
+    team_role: str, scenario_id: str, hint_type: str
+) -> Optional[dict]:
+    """Look up a scenario by id, scoped to the team.
+
+    Tries the hint table first (single round-trip), then falls back to
+    every other table the team owns. This replaces the old behaviour
+    where ``fetch_scenario_by_id`` always looked in
+    ``encryption_challenges`` — which would silently return ``None``
+    for code-fixing / log-analysis / vuln-hunter / web rows.
+    """
+    if not scenario_id:
+        return None
+    tables = [scenario_table(team_role, hint_type)] + [
+        t for t in _tables_for_team(team_role)
+        if t != scenario_table(team_role, hint_type)
+    ]
+    for table in tables:
+        row = await _fetch_scenario_in_table(team_role, scenario_id, table)
+        if row:
+            return row
+    return None
+
+
+async def _fetch_scenario_in_table(
+    team_role: str, scenario_id: str, table: str
+) -> Optional[dict]:
+    import httpx
+    from app.services.supabase_service import supabase_headers
+    from app.core.config import SUPABASE_URL, SUPABASE_ANON_KEY
+    if not SUPABASE_ANON_KEY or not SUPABASE_URL:
+        return None
+    url = (
+        f"{SUPABASE_URL}/rest/v1/{table}"
+        f"?id=eq.{scenario_id}&team_role=eq.{team_role}&limit=1"
+    )
+    try:
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(url, headers=supabase_headers())
+            if resp.status_code == 200:
+                rows = resp.json()
+                if rows:
+                    return rows[0]
+    except Exception as e:
+        print(f"[generate_training] {table} lookup failed: {e}")
+    return None
+
+
+async def _fetch_random_scenario_typed(
+    team_role: str, challenge_type: str
+) -> Optional[dict]:
+    """Pick a random row from the table that matches ``challenge_type``."""
+    from app.services.supabase_service import fetch_all_scenarios_for_type
+    rows = await fetch_all_scenarios_for_type(team_role, challenge_type, limit=50)
+    if rows:
+        return random.choice(rows)
+    return None
+
+
+# --------------------------------------------------------------------------- #
+#  /api/training/evaluate — generic / legacy red+blue                         #
+# --------------------------------------------------------------------------- #
+
+@router.post("/api/training/evaluate")
+async def post_evaluate_training(req: EvaluateRequest, background_tasks: BackgroundTasks):
+    return await evaluate_training(req, background_tasks)
+
+
+# --------------------------------------------------------------------------- #
+#  /api/training/evaluate-web — 3-layer web exploitation validation           #
+# --------------------------------------------------------------------------- #
+
+@router.post("/api/training/evaluate-web")
+async def post_evaluate_web(req: WebEvaluateRequest):
+    return await evaluate_web_exploitation(req)
+
+
+# --------------------------------------------------------------------------- #
+#  /api/training/evaluate-code-fix                                            #
+# --------------------------------------------------------------------------- #
+
+@router.post("/api/training/evaluate-code-fix")
+async def post_evaluate_code_fix(req: CodeFixEvaluateRequest, background_tasks: BackgroundTasks):
+    return await evaluate_code_fix(req, background_tasks)
+
+
+# --------------------------------------------------------------------------- #
+#  /api/training/evaluate-log-analysis                                        #
+# --------------------------------------------------------------------------- #
+
+@router.post("/api/training/evaluate-log-analysis")
+async def post_evaluate_log_analysis(req: LogAnalysisEvaluateRequest, background_tasks: BackgroundTasks):
+    return await evaluate_log_analysis(req, background_tasks)
+
+
+# --------------------------------------------------------------------------- #
+#  /api/training/evaluate-vulnerability-hunter                                #
+# --------------------------------------------------------------------------- #
+
+@router.post("/api/training/evaluate-vulnerability-hunter")
+async def post_evaluate_vuln_hunter(req: VulnHunterEvaluateRequest, background_tasks: BackgroundTasks):
+    return await evaluate_vuln_hunter(req, background_tasks)
+
+
+# Re-export the row mappers so 1v1 can keep importing them from a
+# stable location without taking a hard dependency on the service layer.
+__all__ = [
+    "map_encryption_row_to_training",
+    "map_webex_row_to_training",
+    "map_code_fixing_row_to_training",
+    "map_log_analysis_row_to_training",
+    "map_vuln_hunter_row_to_training",
+]

app/api/xp.py

@@ -0,0 +1,26 @@
+"""``/api/xp`` — proxy to the Supabase ``apex-xp`` edge function."""
+
+import httpx
+from fastapi import APIRouter, HTTPException
+
+from app.core.config import SUPABASE_EDGE_URL
+from app.types import XpRequest
+
+
+router = APIRouter()
+
+
+@router.post("/api/xp")
+async def handle_xp(req: XpRequest):
+    if not req.user_id:
+        raise HTTPException(status_code=400, detail="user_id is required")
+
+    async with httpx.AsyncClient(timeout=30) as client:
+        resp = await client.post(
+            f"{SUPABASE_EDGE_URL}/apex-xp",
+            json={"action": req.action, "user_id": req.user_id, "xp_amount": req.xp_amount},
+        )
+    data = resp.json()
+    if resp.status_code != 200:
+        raise HTTPException(status_code=resp.status_code, detail=data.get("error", "XP operation failed"))
+    return data

app/core/__init__.py

@@ -0,0 +1,68 @@
+"""Core constants and small pure-Python helpers.
+
+Nothing in this package performs I/O — only constants, mappings, and
+deterministic utility functions safe to import from anywhere.
+"""
+
+from .constants import (
+    CYBER_SECURITY_TOPICS,
+    MODULE_TOPIC_MAP,
+    TOPIC_KEYWORDS,
+    FALLBACK_HTML,
+    HELP_TEXT,
+    WEB_EXPLOIT_MODULES,
+    CERT_REQUIRED_COMPLETIONS,
+    CERT_VERIFY_BASE_URL,
+)
+from .config import (
+    SUPABASE_URL,
+    SUPABASE_ANON_KEY,
+    SUPABASE_EDGE_URL,
+    GROQ_API_KEY,
+    GROQ_API_URL,
+    GROQ_DEFAULT_MODEL,
+    MISTRAL_API_KEY,
+    MISTRAL_MODEL,
+    MISTRAL_API_URL,
+    CHALLENGE_FILES_BUCKET,
+)
+from .text import parse_json_safe
+from .security import (
+    normalize_vuln_key,
+    normalize_str,
+    ip_matches,
+    ioc_matches,
+    timestamp_close,
+)
+from .module_router import challenge_type_for_module
+
+__all__ = [
+    # constants
+    "CYBER_SECURITY_TOPICS",
+    "MODULE_TOPIC_MAP",
+    "TOPIC_KEYWORDS",
+    "FALLBACK_HTML",
+    "HELP_TEXT",
+    "WEB_EXPLOIT_MODULES",
+    "CERT_REQUIRED_COMPLETIONS",
+    "CERT_VERIFY_BASE_URL",
+    # config
+    "SUPABASE_URL",
+    "SUPABASE_ANON_KEY",
+    "SUPABASE_EDGE_URL",
+    "GROQ_API_KEY",
+    "GROQ_API_URL",
+    "GROQ_DEFAULT_MODEL",
+    "MISTRAL_API_KEY",
+    "MISTRAL_MODEL",
+    "MISTRAL_API_URL",
+    "CHALLENGE_FILES_BUCKET",
+    # helpers
+    "parse_json_safe",
+    "normalize_vuln_key",
+    "normalize_str",
+    "ip_matches",
+    "ioc_matches",
+    "timestamp_close",
+    "challenge_type_for_module",
+]

app/core/config.py

@@ -0,0 +1,113 @@
+"""Environment-loaded configuration.
+
+All environment variables used anywhere in the backend live here so
+the routers / services never call ``os.environ.get`` directly.
+"""
+
+# Make sure .env is loaded no matter who imports us first.
+from app._env import load_app_env  # noqa: E402
+load_app_env()
+
+import os
+
+# --------------------------------------------------------------------------- #
+#  Supabase                                                                  #
+# --------------------------------------------------------------------------- #
+
+SUPABASE_URL = os.environ.get(
+    "SUPABASE_URL",
+    "https://yevtnyokixocpihpdwqu.supabase.co",
+)
+SUPABASE_ANON_KEY = os.environ.get("SUPABASE_ANON_KEY", "")
+
+
+# --------------------------------------------------------------------------- #
+#  AI providers — endpoints, model names, keys                                #
+# --------------------------------------------------------------------------- #
+
+# Cloudflare Workers AI is the primary tier in the three-tier fallback
+# chain documented in AGENTS.md. It's only used inside individual
+# generators; the main backend talks to Groq / Mistral directly.
+
+# Groq (secondary AI, also the legacy scenario/eval backend).
+GROQ_API_KEY = os.environ.get("GROQ_API_KEY", "")
+GROQ_API_URL = "https://api.groq.com/openai/v1/chat/completions"
+GROQ_DEFAULT_MODEL = os.environ.get("GROQ_MODEL", "llama-3.1-8b-instant")
+
+# Mistral — used for log-analysis Arabic feedback only.
+MISTRAL_API_KEY = os.environ.get("MISTRAL_API_KEY", "")
+MISTRAL_MODEL = os.environ.get("MISTRAL_MODEL", "mistral-large-latest")
+MISTRAL_API_URL = os.environ.get(
+    "MISTRAL_API_URL",
+    "https://api.mistral.ai/v1/chat/completions",
+)
+
+# Supabase Edge Functions used as auth / XP proxies.
+SUPABASE_EDGE_URL = f"{SUPABASE_URL}/functions/v1"
+
+
+# --------------------------------------------------------------------------- #
+#  Supabase Storage bucket for AI-generated challenge files                  #
+# --------------------------------------------------------------------------- #
+
+# Name of the public bucket ``app.services.file_storage`` uploads
+# ``fileToGenerate`` payloads to. The bucket's RLS policies live in
+# ``db/schema/010_challenge_files_bucket.sql``.
+CHALLENGE_FILES_BUCKET = "challenge-files"
+
+
+# --------------------------------------------------------------------------- #
+#  Per-table canonical module (see AGENTS.md "Challenge Type vs Module")     #
+# --------------------------------------------------------------------------- #
+
+# One entry per per-type challenges table — the ONLY value the
+# ``module`` column is allowed to take for rows going into that
+# table. ``normalize_row_module()`` enforces this at insert time so
+# AI generators can keep using topic-shaped names internally
+# (``xss``, ``sqli``, ``hash-cracking``) without violating the
+# post-011 CHECK constraints.
+TABLE_CANONICAL_MODULE: dict[str, str] = {
+    "encryption_challenges":           "crypto",
+    "web_exploitation_challenges":     "web",
+    "code_fixing_challenges":          "code-fixing",
+    "log_analysis_challenges":         "log-analysis",
+    "vulnerability_hunter_challenges": "vulnerability-hunter",
+}
+
+
+def normalize_row_module(table: str, row: dict) -> dict:
+    """Enforce the canonical ``module`` value for a row going to ``table``.
+
+    The migration 011 CHECK constraint rejects any row whose
+    ``module`` column does not equal the canonical challenge type
+    for its table. The AI generators used to populate ``module``
+    with a topic-shaped string (``xss``, ``hash-cracking``,
+    ``web-security``, …) — we transparently rewrite that into:
+
+    * ``module`` = canonical challenge type (so the DB accepts it)
+    * ``topic``  = the original topic-shaped string (so the front-end
+                   can still show / filter on it)
+
+    If the row already carries the canonical value, ``topic`` falls
+    back to whatever ``module`` said. The function returns the
+    mutated ``row`` (in place) for convenience; the return value is
+    the same dict.
+
+    Raises ``ValueError`` when called with an unknown table name —
+    that always indicates a programming error, never a bad row.
+    """
+    canonical = TABLE_CANONICAL_MODULE.get(table)
+    if canonical is None:
+        raise ValueError(
+            f"normalize_row_module: unknown table {table!r}. "
+            f"Add it to app.core.config.TABLE_CANONICAL_MODULE."
+        )
+
+    original = row.get("module", "")
+    # Move the original topic-shaped value into ``topic`` (if not
+    # already set) and pin ``module`` to the canonical challenge type.
+    if row.get("topic") is None or row.get("topic") == "":
+        row["topic"] = original or canonical
+    row["module"] = canonical
+    return row
+

app/core/constants.py

@@ -0,0 +1,153 @@
+"""Pure constants — no I/O, no imports beyond stdlib.
+
+This module is the single source of truth for the topic catalog, the
+difficulty / module maps, and the small strings the backend embeds
+verbatim in HTTP responses (HTML fallback, terminal help text, etc.).
+"""
+
+import os
+
+
+# --------------------------------------------------------------------------- #
+#  Topic catalog (module key -> human-readable name + category + path)        #
+# --------------------------------------------------------------------------- #
+
+MODULE_TOPIC_MAP = {
+    "xss": "ثغرات XSS (Cross-Site Scripting) - هجمات الحقن البرمجي في المتصفح",
+    "sql-injection": "ثغرات SQL Injection - حقن استعلامات خبيثة في قاعدة البيانات",
+    "csrf": "ثغرات CSRF (Cross-Site Request Forgery) - تزوير الطلبات عبر المواقع",
+    "auth-bypass": "ثغرات المصادقة - تجاوز أنظمة تسجيل الدخول",
+    "misconfig": "التكوين الأمني الخاطئ - إعدادات غير آمنة",
+    "packet-analysis": "تحليل حزم الشبكة Network Packet Analysis",
+    "firewall": "جدران الحماية Firewall Configuration",
+    "scanning": "مسح الشبكات Network Scanning",
+    "encryption-basics": "أساسيات التشفير Encryption",
+    "hash-cracking": "كسر الهاش Hash Cracking",
+    "log-analysis": "تحليل سجلات الخادم Log Analysis",
+    "forensics": "الأدلة الرقمية Forensics",
+}
+
+
+CYBER_SECURITY_TOPICS = {
+    # 1. Web Security
+    "xss": {"name": "ثغرات XSS (Cross-Site Scripting)", "category": "Web Security", "path": "web-security"},
+    "sql-injection": {"name": "ثغرات SQL Injection", "category": "Web Security", "path": "web-security"},
+    "csrf": {"name": "ثغرات CSRF (Cross-Site Request Forgery)", "category": "Web Security", "path": "web-security"},
+    "ssrf": {"name": "ثغرات SSRF (Server-Side Request Forgery)", "category": "Web Security", "path": "web-security"},
+    "idor": {"name": "ثغرات IDOR (Insecure Direct Object Reference)", "category": "Web Security", "path": "web-security"},
+    "lfi-rfi": {"name": "ثغرات تضمين الملفات LFI/RFI", "category": "Web Security", "path": "web-security"},
+    "xxe": {"name": "ثغرات XML External Entity (XXE)", "category": "Web Security", "path": "web-security"},
+    "command-injection": {"name": "حقن الأوامر البرمجية Command Injection", "category": "Web Security", "path": "web-security"},
+    # New 10-module set (replaces the 13 above)
+    "sqli":   {"name": "ثغرات SQL Injection",        "category": "Web Security", "path": "web-security"},
+    "cmdi":   {"name": "حقن الأوامر Command Injection","category": "Web Security", "path": "web-security"},
+    "auth":   {"name": "ثغرات المصادقة Auth Flaws",    "category": "Web Security", "path": "web-security"},
+    "upload": {"name": "رفع الملفات الخبيثة Upload",    "category": "Web Security", "path": "web-security"},
+
+    # 2. Network Security
+    "packet-analysis": {"name": "تحليل حزم الشبكات Packet Analysis", "category": "Network Security", "path": "network-security"},
+    "firewall": {"name": "إعدادات وجدران الحماية Firewall", "category": "Network Security", "path": "network-security"},
+    "scanning": {"name": "مسح وتفحص الشبكات Network Scanning", "category": "Network Security", "path": "network-security"},
+    "mitm": {"name": "هجمات رجل في المنتصف MITM Attacks", "category": "Network Security", "path": "network-security"},
+    "dns-poisoning": {"name": "تسميم سجلات الـ DNS", "category": "Network Security", "path": "network-security"},
+
+    # 3. Cryptography
+    "encryption-basics": {"name": "أساسيات التشفير وفك الترميز", "category": "Cryptography", "path": "cryptography"},
+    "hash-cracking": {"name": "كسر شفرات الهاش Hash Cracking", "category": "Cryptography", "path": "cryptography"},
+    "rsa-aes": {"name": "خوارزميات التشفير المتقدمة RSA/AES", "category": "Cryptography", "path": "cryptography"},
+    "steganography": {"name": "إخفاء المعلومات في الوسائط Steganography", "category": "Cryptography", "path": "cryptography"},
+
+    # 4. Reverse Engineering & Binaries
+    "binary-analysis": {"name": "تحليل الملفات الثنائية Binary Analysis", "category": "Reverse Engineering", "path": "reverse-engineering"},
+    "assembly-cracking": {"name": "هندسة الأكواد العكسية وقراءة الأسمبلي", "category": "Reverse Engineering", "path": "reverse-engineering"},
+
+    # 5. OS & Systems Security
+    "linux-privesc": {"name": "تصعيد الصلاحيات في أنظمة Linux", "category": "Systems Security", "path": "systems-security"},
+    "windows-privesc": {"name": "تصعيد الصلاحيات في أنظمة Windows", "category": "Systems Security", "path": "systems-security"},
+    "active-directory": {"name": "اختراق وإدارة بيئة الـ Active Directory", "category": "Systems Security", "path": "systems-security"},
+
+    # 6. Mobile Security
+    "android-ios": {"name": "أمن تطبيقات الهواتف الذكية Android/iOS", "category": "Mobile Security", "path": "mobile-security"},
+
+    # 7. Cloud Security
+    "cloud-config": {"name": "أمن الخدمات السحابية وتهيئة الحاويات Docker/Kubernetes", "category": "Cloud Security", "path": "cloud-security"},
+
+    # 8. Digital Forensics & Log Analysis
+    "log-analysis": {"name": "تحليل سجلات الخادم والأنظمة Log Analysis", "category": "Digital Forensics", "path": "forensics"},
+    "memory-forensics": {"name": "تحليل الذاكرة العشوائية Memory Forensics", "category": "Digital Forensics", "path": "forensics"},
+
+    # 9. Code Fixing (Blue Team)
+    "code-fixing": {"name": "تصحيح الكود المصاب بثغرات أمنية", "category": "تصحيح الكود (Code Fixing)", "path": "code-fixing"},
+    "web-security": {"name": "تصحيح الكود المصاب بثغرات أمنية", "category": "تصحيح الكود (Code Fixing)", "path": "code-fixing"},
+    "systems-security": {"name": "تصحيح الكود المصاب بثغرات أمنية", "category": "تصحيح الكود (Code Fixing)", "path": "code-fixing"},
+
+    # 10. Vulnerability Hunter (Blue Team)
+    "vulnerability-hunter": {"name": "صياد الثغرات Vulnerability Hunter", "category": "Vulnerability Hunter", "path": "vulnerability-hunter"},
+}
+
+
+TOPIC_KEYWORDS = {
+    "xss": ["xss", "cross-site", "حقن نصوص", "innerHTML", "script", "تعليق", "textContent"],
+    "sql-injection": ["sql", "injection", "استعلام", "قاعدة بيانات", "database", "query", "select", "union"],
+    "csrf": ["csrf", "forgery", "تزوير الطلبات", "طلب عبر المواقع", "token", "رمز الحماية"],
+    "ssrf": ["ssrf", "server-side request", "تزوير الطلب من جانب الخادم", "طلب داخلي", "fetch"],
+    "idor": ["idor", "direct object", "معرف", "رابط مباشر", "projectId", "userId", "OID"],
+    "lfi-rfi": ["lfi", "rfi", "تضمين", "ملفات", "include", "file inclusion"],
+    "xxe": ["xxe", "xml", "external entity", "كيان خارجي", "entity"],
+    "command-injection": ["command", "أوامر", "exec", "system", "حقن الأوامر"],
+    "packet-analysis": ["packet", "حزم", "شبكة", "pcap", "wireshark", "تحليل حزم"],
+    "firewall": ["firewall", "جدار حماية", "جدران حماية", "قواعد المرور", "port", "منفذ"],
+    "scanning": ["scan", "مسح", "فحص شبكات", "nmap", "منفذ مفتوح", "ports"],
+    "mitm": ["mitm", "رجل في المنتصف", "منصف", "تسميم", "arp poisoning", "dns poisoning"],
+    "dns-poisoning": ["dns", "poisoning", "تسميم سجلات", "نظام أسماء النطاقات"],
+    "encryption-basics": ["encryption", "تشفير", "فك ترميز", "base64", "rot13", "caesar", "cipher"],
+    "hash-cracking": ["hash", "هاش", "md5", "sha", "cracking", "كسر"],
+    "rsa-aes": ["rsa", "aes", "خوارزميات التشفير المتقدمة"],
+    "steganography": ["steganography", "إخفاء", "وسائط", "صورة", "ملف مخفي"],
+    "binary-analysis": ["binary", "ثنائي", "ملف ثنائي", "قراءة الملفات الثنائية"],
+    "assembly-cracking": ["assembly", "أسمبلي", "عكسي", "هندسة عكسية"],
+    "linux-privesc": ["linux", "صلاحيات root", "تصعيد", "privilege escalation"],
+    "windows-privesc": ["windows", "صلاحيات", "تصعيد", "administrator"],
+    "active-directory": ["active directory", "دليل نشط", "kerberos", "domain controller"],
+    "android-ios": ["android", "ios", "هاتف", "تطبيق ذكي", "موبايل"],
+    "cloud-config": ["cloud", "docker", "kubernetes", "سحابية", "حاويات"],
+    "log-analysis": ["log", "سجل", "سجلات", "خادم", "تحليل سجلات"],
+    "memory-forensics": ["memory", "ذاكرة عشوائية", "forensics", "volatility"],
+}
+
+
+# Web exploitation module set (Red Team offensive) — used by
+# app.core.module_router.challenge_type_for_module.
+WEB_EXPLOIT_MODULES = {
+    "xss", "sqli", "csrf", "ssrf",
+    "idor", "lfi-rfi", "xxe", "cmdi",
+    "auth", "upload",
+}
+
+
+# --------------------------------------------------------------------------- #
+#  Embedded HTML / text the backend serves when AI generation fails            #
+# --------------------------------------------------------------------------- #
+
+FALLBACK_HTML = """<!DOCTYPE html><html dir="rtl" lang="ar"><head><meta charset="UTF-8"><style>body{margin:0;padding:40px;font-family:sans-serif;background:#0b0b12;color:#fff;display:flex;flex-direction:column;align-items:center;justify-content:center;min-height:100vh;text-align:center}h1{color:#00d4aa;font-size:22px;margin-bottom:16px}p{color:rgba(255,255,255,0.6);font-size:14px;line-height:1.8;max-width:500px}</style></head><body><h1>🔐 منصة APEX للتدريب</h1><p>بيئة التدريب التفاعلية جاهزة. اتبع التعليمات في لوحة المهام على اليمين لإكمال التحدي.</p></body></html>"""
+
+
+HELP_TEXT = """الأوامر الأساسية (تعمل دائماً):
+  ls, cat <file>, pwd, echo <text>, whoami, clear, help
+  sha256sum <file>, md5sum <file>, sha1sum <file>
+  base64 [-d] <file>     ترميز/فك Base64
+  xxd <file>             عرض hex
+  tr SET1 SET2 <text>    استبدال أحرف
+
+الأدوات الخارجية (مفعّلة لهذا التحدي): انظر whitelist في Cheat Sheet.
+  مثال:  python -c "print('hello')"
+          openssl enc -d -aes-256-cbc -in f.enc -k SECRET
+"""
+
+
+# --------------------------------------------------------------------------- #
+#  Certificate system tuning                                                 #
+# --------------------------------------------------------------------------- #
+
+CERT_REQUIRED_COMPLETIONS = 50
+CERT_VERIFY_BASE_URL = os.environ.get("CERT_VERIFY_BASE_URL", "").rstrip("/")

app/core/module_router.py

@@ -0,0 +1,19 @@
+"""Map module names to challenge types and back.
+
+The frontend uses ``module`` to route a row to the right editor.
+We keep two parallel maps and a single function for clarity.
+"""
+
+from .constants import WEB_EXPLOIT_MODULES
+
+
+def challenge_type_for_module(module: str) -> str:
+    """Return challenge type for a module name.
+
+    Currently: ``"web"`` for the offensive web-exploitation set,
+    ``"crypto"`` for the legacy crypto challenges. New challenge types
+    are wired by extending this function — no caller change required.
+    """
+    if module in WEB_EXPLOIT_MODULES:
+        return "web"
+    return "crypto"

app/core/security.py

@@ -0,0 +1,61 @@
+"""Normalization helpers used by the evaluators.
+
+Each function is intentionally tiny and side-effect-free so the
+1v1 verifier and the regular /evaluate endpoint can call the same code
+and stay in lock-step.
+"""
+
+import re
+
+
+def normalize_vuln_key(s: str) -> str:
+    """Canonicalise a typed vulnerability key.
+
+    Rules:
+      - lowercase
+      - trim
+      - replace spaces / underscores with dashes
+      - strip surrounding punctuation
+    """
+    if not s:
+        return ""
+    s = s.strip().lower()
+    s = re.sub(r"[\s_]+", "-", s)
+    s = re.sub(r"[^a-z0-9\-]", "", s)
+    return s
+
+
+def normalize_str(s: str) -> str:
+    return (s or "").strip().lower()
+
+
+def ip_matches(user_ip: str, expected_ip: str) -> bool:
+    """Loose IP match: trim, lowercase, ignore trailing port or zone id."""
+    u = normalize_str(user_ip).split("/")[0]
+    e = normalize_str(expected_ip).split("/")[0]
+    return u == e and u != ""
+
+
+def ioc_matches(user_ioc: str, expected_ioc: str) -> bool:
+    """IOC match: case-insensitive substring."""
+    u = normalize_str(user_ioc)
+    e = normalize_str(expected_ioc)
+    if not u or not e:
+        return False
+    return e in u or u in e
+
+
+def timestamp_close(user_ts: str, expected_ts: str) -> bool:
+    """Timestamp match: exact OR every alphanumeric token of the expected
+    timestamp appears in the user input (lenient by design)."""
+    u = normalize_str(user_ts)
+    e = normalize_str(expected_ts)
+    if not u or not e:
+        return False
+    if u == e:
+        return True
+    # Try day-hour match (e.g., "15/Dec" or "Mar 12" or "2024-11-08")
+    e_tokens = re.findall(r"[a-zA-Z]+|\d+", e)
+    if not e_tokens:
+        return False
+    return all(tok.lower() in u for tok in e_tokens[:2])

app/core/text.py

@@ -0,0 +1,42 @@
+"""JSON parsing helpers used by every AI call site."""
+
+import json
+import re
+
+
+def parse_json_safe(raw: str) -> dict:
+    """Best-effort JSON parser for raw LLM output.
+
+    Handles three common failure modes:
+      1. The model wraps the object in ```json ... ``` fences.
+      2. The model adds prose before/after the object.
+      3. The model emits literal control characters (newlines, tabs)
+         inside a string value that ``json.loads`` rejects.
+    """
+    cleaned = raw.strip()
+
+    fence_match = re.search(r"```(?:json)?\s*([\s\S]*?)```", cleaned, re.IGNORECASE)
+    if fence_match:
+        cleaned = fence_match.group(1).strip()
+
+    start = cleaned.find("{")
+    end = cleaned.rfind("}")
+    if start != -1 and end != -1 and end > start:
+        cleaned = cleaned[start:end + 1]
+
+    cleaned = re.sub(r"[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]", "", cleaned)
+
+    try:
+        # Use strict=False to allow literal control characters (like newlines) in strings
+        return json.loads(cleaned, strict=False)
+    except json.JSONDecodeError as exc:
+        # One last ditch effort: replace literal newlines with escaped ones
+        try:
+            # This is risky but sometimes helps with unescaped newlines in middle of strings
+            cleaned_fix = cleaned.replace('\n', '\\n').replace('\r', '\\r')
+            # But the start/end might be messed up now if it was already formatted.
+            # Let's just try strict=False first as it's the standard solution for "control character" errors.
+            return json.loads(cleaned, strict=False)
+        except Exception:
+            preview = raw[:500].replace("\n", " ")
+            raise ValueError(f"Invalid JSON from model: {exc}. Raw preview: {preview}") from exc

app/generators/__init__.py

@@ -0,0 +1,40 @@
+"""Per-challenge-type pool generators.
+
+Each module here owns ONE challenge table and exposes the same public API
+that :func:`app.main.populate_pool_background` consumes:
+
+    POOL_TARGET / POOL_THRESHOLD / POOL_BATCH  (module-level constants)
+    async get_pool_count(team_role) -> int
+    async refill_pool(team_role, count) -> int
+    async start_pool_watcher(team_role)        # long-running coroutine
+
+The five generators currently registered are: crypto, web, code-fixing,
+log-analysis, and vulnerability-hunter.
+"""
+
+from . import crypto
+from . import web
+from . import code_fixing
+from . import log_analysis
+from . import vulnerability_hunter
+
+# The orchestrator in app.main iterates this registry. A new challenge
+# type is added by appending a tuple below (and a matching table in
+# app.services.supabase_service.scenario_table).
+REGISTRY = [
+    # (slug, module, list_of_teams)
+    ("crypto",               crypto,                ["red"]),
+    ("web",                  web,                   ["red"]),
+    ("code-fixing",          code_fixing,           ["blue"]),
+    ("log-analysis",         log_analysis,          ["blue"]),
+    ("vulnerability-hunter", vulnerability_hunter,  ["blue"]),
+]
+
+__all__ = [
+    "crypto",
+    "web",
+    "code_fixing",
+    "log_analysis",
+    "vulnerability_hunter",
+    "REGISTRY",
+]

code_fixing_generator.py → app/generators/code_fixing.py

@@ -166,6 +166,13 @@ NVIDIA_API_KEY = os.environ.get("NVIDIA_API_KEY", "")
 NVIDIA_MODEL = os.environ.get("NVIDIA_MODEL", "deepseek-ai/deepseek-v4-pro")
 NVIDIA_API_URL = "https://integrate.api.nvidia.com/v1/chat/completions"
 
+# Mistral — primary AI for challenge generation (per the user's request).
+MISTRAL_API_KEY = os.environ.get("MISTRAL_API_KEY", "")
+MISTRAL_MODEL = os.environ.get("MISTRAL_MODEL", "mistral-large-latest")
+MISTRAL_API_URL = os.environ.get(
+    "MISTRAL_API_URL", "https://api.mistral.ai/v1/chat/completions"
+)
+
 TABLE_NAME = "code_fixing_challenges"
 
 # Per-team backoff tracker
@@ -780,6 +787,52 @@ async def _post_with_json_fallback(client, url: str, payload: dict, headers: dic
     return resp
 
 
+async def _try_mistral(prompt: str, system: str, model: str) -> Optional[str]:
+    """Try Mistral API (mistral-large-latest by default).
+
+    Per the user's request, Mistral is the PRIMARY tier for challenge
+    generation — it runs first in the orchestrator. Only on a hard
+    failure (429 / timeout / 5xx / parse) do we fall through to
+    Cloudflare, then Groq, then NVIDIA/DeepSeek, then seed.
+    """
+    if not MISTRAL_API_KEY:
+        return None
+    import httpx as _httpx
+    try:
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {MISTRAL_API_KEY}",
+        }
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+        payload = {
+            "model": model or MISTRAL_MODEL,
+            "messages": messages,
+            "temperature": 0.7,
+            "max_tokens": 4096,
+            "response_format": {"type": "json_object"},
+        }
+        async with _httpx.AsyncClient(timeout=30) as client:
+            resp = await _post_with_json_fallback(client, MISTRAL_API_URL, payload, headers, "mistral")
+        if resp.status_code == 200:
+            data = resp.json()
+            content = data.get("choices", [{}])[0].get("message", {}).get("content")
+            if content:
+                return content
+            print(f"  [mistral] 200 but empty content: {str(data)[:200]}")
+            return None
+        if resp.status_code == 429:
+            print(f"  [mistral] 429 rate-limited")
+        else:
+            print(f"  [mistral] error {resp.status_code}: {resp.text[:200]}")
+        return None
+    except Exception as e:
+        print(f"  [mistral] exception: {type(e).__name__}: {e}")
+        return None
+
+
 async def _try_cloudflare(prompt: str, system: str) -> Optional[str]:
     """Try Cloudflare Workers AI. Cycles through multiple models until one works.
     Returns raw text on success, None if all models fail.
@@ -809,7 +862,7 @@ async def _try_cloudflare(prompt: str, system: str) -> Optional[str]:
         }
         payload = {**payload_base, "response_format": {"type": "json_object"}}
         try:
-            async with _httpx.AsyncClient(timeout=120) as client:
+            async with _httpx.AsyncClient(timeout=30) as client:
                 resp = await _post_with_json_fallback(client, url, payload, headers, f"cloudflare/{model_name.split('/')[-1]}")
             if resp.status_code == 200:
                 result = resp.json()
@@ -910,10 +963,14 @@ async def _try_nvidia(prompt: str, system: str, model: str) -> Optional[str]:
 
 
 async def _call_ai(prompt: str, system: str = "", model: str = "") -> Optional[str]:
-    """Try providers in strict order: Cloudflare -> Groq -> NVIDIA/DeepSeek.
+    """Try providers in strict order: Mistral -> Cloudflare -> Groq -> NVIDIA/DeepSeek.
     Returns the first valid response, or None if all fail.
     Each provider must return successfully; the call to parse_json_safe happens later.
     """
+    print(f"  [ai] Trying Mistral...")
+    r = await _try_mistral(prompt, system, model)
+    if r:
+        return r
     print(f"  [ai] Trying Cloudflare...")
     r = await _try_cloudflare(prompt, system)
     if r:
@@ -926,7 +983,7 @@ async def _call_ai(prompt: str, system: str = "", model: str = "") -> Optional[s
     r = await _try_nvidia(prompt, system, model)
     if r:
         return r
-    print(f"  [ai] All 3 providers failed")
+    print(f"  [ai] All 4 providers failed")
     return None
 
 
@@ -1054,6 +1111,12 @@ async def get_pool_count(team_role: str) -> int:
 async def _insert_to_db(row: dict) -> bool:
     if not SUPABASE_ANON_KEY or not SUPABASE_URL:
         return False
+    # Enforce the migration 011 CHECK constraint: ``module`` MUST
+    # be the canonical challenge type ('code-fixing') for this
+    # table — the AI / seed rows used to carry topic-shaped values
+    # like 'web-security' or 'systems-security'.
+    from app.core.config import normalize_row_module
+    row = normalize_row_module(TABLE_NAME, row)
     url = f"{SUPABASE_URL}/rest/v1/{TABLE_NAME}"
     headers = supabase_headers(content_type=True)
     headers["Prefer"] = "return=representation"
@@ -1130,7 +1193,15 @@ async def refill_pool(team_role: str, count: int) -> int:
                 return True
         return False
 
-    results = await asyncio.gather(*[_gen_one(i) for i in range(target)])
+    # Sequential generation: each challenge is fully generated, validated,
+    # inserted, AND confirmed in the DB before the next one starts. Hitting
+    # the AI in parallel triggers Mistral/CF 429 rate limits.
+    results = []
+    for i in range(target):
+        ok = await _gen_one(i)
+        results.append(ok)
+        # Small backoff between calls to stay well under per-minute quotas.
+        await asyncio.sleep(2.0)
     return sum(1 for r in results if r)
 
 
@@ -1162,12 +1233,13 @@ async def start_pool_watcher(team_role: str):
 
     print(f"[code-fixing] Pool watcher started for '{team_role}' (target={POOL_TARGET}, threshold={POOL_THRESHOLD}, batch={POOL_BATCH})")
 
-    # Pre-warm at startup
+    # Pre-warm at startup — tries AI first (Mistral → CF → Groq → NVIDIA),
+    # falls back to seeds only if every AI tier fails.
     try:
         current = await get_pool_count(team_role)
         if current < POOL_TARGET:
             print(f"[code-fixing] Pre-warming pool ({current} → {POOL_TARGET})...")
-            added = await _refill_with_seeds_only(team_role, POOL_TARGET - current)
+            added = await refill_pool(team_role, POOL_TARGET - current)
             print(f"[code-fixing] Pre-warm done: +{added} challenges")
     except Exception as e:
         print(f"[code-fixing] Pre-warm failed: {e}")
@@ -1180,6 +1252,7 @@ async def start_pool_watcher(team_role: str):
                 added = await refill_pool(team_role, POOL_BATCH)
                 print(f"[code-fixing] Refill done: +{added} (now {count + added}/{POOL_TARGET})")
                 await asyncio.sleep(2)
+            # else: pool healthy — silent (keep logs clean)
             else:
                 await asyncio.sleep(30)
         except Exception as e:

crypto_generator.py → app/generators/crypto.py

@@ -320,6 +320,13 @@ NVIDIA_API_KEY = os.environ.get("NVIDIA_API_KEY", "")
 NVIDIA_MODEL = os.environ.get("NVIDIA_MODEL", "deepseek-ai/deepseek-v4-pro")
 NVIDIA_URL = "https://integrate.api.nvidia.com/v1/chat/completions"
 
+# PRIMARY AI: Mistral (per the user's request — Mistral runs first)
+MISTRAL_API_KEY = os.environ.get("MISTRAL_API_KEY", "")
+MISTRAL_MODEL = os.environ.get("MISTRAL_MODEL", "mistral-large-latest")
+MISTRAL_API_URL = os.environ.get(
+    "MISTRAL_API_URL", "https://api.mistral.ai/v1/chat/completions"
+)
+
 # Flag format: CyberArena{<hex>}
 FLAG_PREFIX = "CyberArena{"
 
@@ -1133,6 +1140,12 @@ def insert_to_db(challenge: Challenge, supabase_url: str = SUPABASE_URL,
         "Prefer": "return=minimal",
     }
     payload = challenge.to_db_row()
+    # Enforce the migration 011 CHECK constraint: ``module`` MUST be
+    # the canonical challenge type ('crypto') for this table — the
+    # AI / seed rows used to carry topic-shaped values like
+    # 'encryption-basics', 'hash-cracking' or 'rsa-aes'.
+    from app.core.config import normalize_row_module
+    payload = normalize_row_module("encryption_challenges", payload)
     last_err: str = ""
     for attempt in range(1, 4):
         try:
@@ -1837,6 +1850,96 @@ def get_pool_count(team_role: str, module: Optional[str] = None) -> int:
     return 0
 
 
+
+async def ai_generate_scenario_via_mistral(team_role: str, module: str, difficulty: str,
+                                            mistral_api_key: str,
+                                            model: str | None = None,
+                                            algorithm: str | None = None) -> ScenarioSpec:
+    """Primary AI: call Mistral (mistral-large-latest) for scenario generation.
+
+    Per the user's request, Mistral is the first provider tried for
+    challenge generation. OpenAI-compatible chat-completions endpoint.
+    Returns a ScenarioSpec the same way ai_generate_scenario does.
+    Raises on transport errors so the caller can decide what to do
+    next (fall back to Cloudflare, then Groq, then NVIDIA/DeepSeek,
+    then seed).
+
+    The ``algorithm`` is pre-selected by the system; the AI is asked
+    to write a story that fits it, not to invent one.
+    """
+    if not mistral_api_key:
+        raise RuntimeError("MISTRAL_API_KEY not configured")
+    model = model or MISTRAL_MODEL
+    prompt = CRYPTO_SCENARIO_PROMPT.format(
+        team_role=team_role, module=module, difficulty=difficulty,
+        algorithm=algorithm or "any",
+    )
+    body = {
+        "model": model,
+        "messages": [
+            {"role": "system", "content": "You output valid JSON only. No prose, no markdown fences."},
+            {"role": "user", "content": prompt},
+        ],
+        "temperature": 0.7,
+        "max_tokens": 2500,
+        "response_format": {"type": "json_object"},
+    }
+    async with httpx.AsyncClient(timeout=60) as client:
+        r = await client.post(
+            MISTRAL_API_URL,
+            headers={"Authorization": f"Bearer {mistral_api_key}", "Content-Type": "application/json"},
+            json=body,
+        )
+    if r.status_code == 429:
+        raise RuntimeError("429 from Mistral - rate limit")
+    if r.status_code != 200:
+        raise RuntimeError(f"Mistral HTTP {r.status_code}: {r.text[:200]}")
+
+    content = (r.json().get("choices") or [{}])[0].get("message", {}).get("content", "")
+    if not content:
+        raise RuntimeError("Mistral returned empty content")
+
+    if "```" in content:
+        m = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", content, re.DOTALL)
+        if m:
+            content = m.group(1)
+    content = content.strip()
+    if content.lower().startswith("json"):
+        content = content[4:]
+    content = content.strip().rstrip("`")
+
+    data = _repair_json(content)
+    extra = data.get("extra", {}) or {}
+    if "filename" not in extra or not extra["filename"]:
+        m = _FILENAME_RE.findall(data.get("story", "") or "")
+        if m:
+            extra["filename"] = m[0]
+    if extra.get("filename"):
+        data["story"] = _align_filename_in_story(data.get("story", ""), extra["filename"])
+        data["task_outline"] = _align_filename_in_story(data.get("task_outline", ""), extra["filename"])
+    data["task_outline"] = _sanitize_task_outline(data.get("task_outline", ""))
+
+    final_algo = _normalize_algo(algorithm or data.get("algorithm", ""))
+    ai_key = (data.get("key_material") or "").strip()
+    if ai_key:
+        key_material, extra = ai_key, extra
+    else:
+        key_material, extra = _generate_key_for_algo(final_algo, extra)
+
+    hints_raw = data.get("hints") or []
+    if isinstance(hints_raw, list):
+        hints = [str(h).strip() for h in hints_raw if str(h).strip()]
+    else:
+        hints = []
+
+    return ScenarioSpec(
+        team_role=team_role, module=module, difficulty=difficulty,
+        algorithm=final_algo, plaintext=data["plaintext"],
+        key_material=key_material,
+        title=data["title"], story=data["story"], task_outline=data["task_outline"],
+        extra=extra, hints=hints,
+    )
+
 async def refill_pool(team_role: str, count: int = POOL_BATCH,
                        groq_api_key: str = GROQ_API_KEY) -> int:
     """Generate and insert up to `count` challenges for a team.
@@ -1894,11 +1997,36 @@ async def _refill_pool_unlocked(team_role: str, count: int,
         difficulty = difficulties[i % len(difficulties)]
         spec = None
         source = "ai"
+        _maybe_try_cf = False
         _maybe_try_groq = False
         _maybe_try_deepseek = False
 
-        # ---- 1) Cloudflare (PRIMARY AI) ----
-        if CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID:
+        # ---- 0) Mistral (PRIMARY AI per user request) ----
+        if MISTRAL_API_KEY:
+            try:
+                spec = await ai_generate_scenario_via_mistral(
+                    team_role, module, difficulty,
+                    MISTRAL_API_KEY,
+                    algorithm=algorithm,
+                )
+                print(f"[crypto_generator] Mistral OK: algo={spec.algorithm} title={spec.title[:50]}")
+            except Exception as e:
+                err = str(e)
+                if "429" in err or "Rate Limit" in err:
+                    print(f"[crypto_generator] Mistral 429 — falling through to Cloudflare")
+                    _maybe_try_cf = True
+                elif "Could not repair JSON" in err or "empty content" in err:
+                    print(f"[crypto_generator] Mistral bad response ({type(e).__name__}) — trying Cloudflare")
+                    _maybe_try_cf = True
+                else:
+                    print(f"[crypto_generator] Mistral failed ({type(e).__name__}): {e} — trying Cloudflare")
+                    _maybe_try_cf = True
+            await asyncio.sleep(0.3)
+        else:
+            _maybe_try_cf = bool(CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID)
+
+        # ---- 1) Cloudflare (SECONDARY AI) ----
+        if spec is None and _maybe_try_cf and CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID:
             try:
                 spec = await ai_generate_scenario_via_cloudflare(
                     team_role, module, difficulty,
@@ -2061,8 +2189,7 @@ async def start_pool_watcher(team_role: str, groq_api_key: str = GROQ_API_KEY) -
                         new_count = count + added
                         print(f"{label} refilled: {count} → {new_count} (target {POOL_TARGET}).")
                         sleep_secs = 5
-                    else:
-                        print(f"{label} pool healthy ({count}/{POOL_TARGET}) — sleeping {IDLE_POLL_SECS}s.")
+                    # else: pool healthy — silent (keep logs clean)
                 await asyncio.sleep(sleep_secs)
             except Exception as e:
                 import traceback

log_analysis_generator.py → app/generators/log_analysis.py

@@ -147,6 +147,13 @@ NVIDIA_API_KEY = os.environ.get("NVIDIA_API_KEY", "")
 NVIDIA_MODEL = os.environ.get("NVIDIA_MODEL", "deepseek-ai/deepseek-v4-pro")
 NVIDIA_API_URL = "https://integrate.api.nvidia.com/v1/chat/completions"
 
+# PRIMARY AI: Mistral (per the user's request — Mistral runs first)
+MISTRAL_API_KEY = os.environ.get("MISTRAL_API_KEY", "")
+MISTRAL_MODEL = os.environ.get("MISTRAL_MODEL", "mistral-large-latest")
+MISTRAL_API_URL = os.environ.get(
+    "MISTRAL_API_URL", "https://api.mistral.ai/v1/chat/completions"
+)
+
 TABLE_NAME = "log_analysis_challenges"
 
 # Per-team backoff tracker
@@ -700,6 +707,51 @@ async def _post_with_json_fallback(client, url: str, payload: dict, headers: dic
     return resp
 
 
+async def _try_mistral(prompt: str, system: str, model: str) -> Optional[str]:
+    """Try Mistral API (mistral-large-latest by default).
+
+    Per the user's request, Mistral is the PRIMARY tier for challenge
+    generation — it runs first in the orchestrator. Only on a hard
+    failure (429 / timeout / 5xx / parse) do we fall through to
+    Cloudflare, then Groq, then NVIDIA/DeepSeek, then seed.
+    """
+    if not MISTRAL_API_KEY:
+        return None
+    try:
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {MISTRAL_API_KEY}",
+        }
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+        payload = {
+            "model": model or MISTRAL_MODEL,
+            "messages": messages,
+            "temperature": 0.7,
+            "max_tokens": 2500,
+            "response_format": {"type": "json_object"},
+        }
+        async with httpx.AsyncClient(timeout=30) as client:
+            resp = await _post_with_json_fallback(client, MISTRAL_API_URL, payload, headers, "mistral")
+        if resp.status_code == 200:
+            data = resp.json()
+            content = data.get("choices", [{}])[0].get("message", {}).get("content")
+            if content:
+                return content
+            print(f"  [mistral] 200 but empty content: {str(data)[:200]}")
+            return None
+        if resp.status_code == 429:
+            print(f"  [mistral] 429 rate-limited")
+        else:
+            print(f"  [mistral] error {resp.status_code}: {resp.text[:200]}")
+        return None
+    except Exception as e:
+        print(f"  [mistral] exception: {type(e).__name__}: {e}")
+        return None
+
+
 async def _try_cloudflare(prompt: str, system: str) -> Optional[str]:
     """Try Cloudflare Workers AI.
 
@@ -840,7 +892,11 @@ async def _try_nvidia(prompt: str, system: str, model: str) -> Optional[str]:
 
 
 async def _call_ai(prompt: str, system: str = "") -> Optional[str]:
-    """Try Cloudflare -> Groq -> NVIDIA. Returns first success."""
+    """Try Mistral -> Cloudflare -> Groq -> NVIDIA. Returns first success."""
+    print(f"  [ai] Trying Mistral...")
+    r = await _try_mistral(prompt, system, "")
+    if r:
+        return r
     print(f"  [ai] Trying Cloudflare...")
     r = await _try_cloudflare(prompt, system)
     if r:
@@ -973,6 +1029,13 @@ async def get_pool_count(team_role: str) -> int:
 async def _insert_to_db(row: dict) -> bool:
     if not SUPABASE_ANON_KEY or not SUPABASE_URL:
         return False
+    # Enforce the migration 011 CHECK constraint: ``module`` MUST be
+    # the canonical challenge type ('log-analysis') for this table.
+    # log-analysis already happens to use the same value as the
+    # topic so this is mostly a no-op, but it also pins ``topic``
+    # for consistency with the other 4 generators.
+    from app.core.config import normalize_row_module
+    row = normalize_row_module(TABLE_NAME, row)
     url = f"{SUPABASE_URL}/rest/v1/{TABLE_NAME}"
     headers = supabase_headers(content_type=True)
     headers["Prefer"] = "return=representation"
@@ -1158,7 +1221,14 @@ async def refill_pool(team_role: str, count: int) -> int:
         return False
 
     # Generate all target challenges in parallel
-    results = await asyncio.gather(*[_gen_one(i) for i in range(target)])
+    # Sequential generation: each challenge is fully generated, validated,
+    # inserted, AND confirmed in the DB before the next one starts. Hitting
+    # the AI in parallel triggers Mistral/CF 429 rate limits.
+    results = []
+    for i in range(target):
+        results.append(await _gen_one(i))
+        # Small backoff between calls to stay well under per-minute quotas.
+        await asyncio.sleep(2.0)
     return sum(1 for r in results if r)
 
 
@@ -1187,13 +1257,14 @@ async def start_pool_watcher(team_role: str):
     """
     print(f"[log-analysis] Pool watcher started for {team_role} (target={POOL_TARGET}, threshold={POOL_THRESHOLD}, batch={POOL_BATCH})")
 
-    # Pre-warm at startup
+    # Pre-warm at startup — tries AI first (Mistral → CF → Groq → NVIDIA),
+    # falls back to seeds only if every AI tier fails.
     try:
         current = await get_pool_count(team_role)
         if current < POOL_TARGET:
             print(f"[log-analysis] Pre-warming pool ({current} → {POOL_TARGET})...")
-            added = await _refill_with_seeds_only(team_role, POOL_TARGET - current)
-            print(f"[log-analysis] Pre-warm done: +{added} seed challenges")
+            added = await refill_pool(team_role, POOL_TARGET - current)
+            print(f"[log-analysis] Pre-warm done: +{added} challenges")
     except Exception as e:
         print(f"[log-analysis] Pre-warm failed: {e}")
 
@@ -1205,6 +1276,7 @@ async def start_pool_watcher(team_role: str):
                 added = await refill_pool(team_role, POOL_BATCH)
                 print(f"[log-analysis] Refill done: +{added} (now {count + added}/{POOL_TARGET})")
                 await asyncio.sleep(2)
+            # else: pool healthy — silent (keep logs clean)
             else:
                 await asyncio.sleep(30)
         except Exception as e:

vulnerability_hunter_generator.py → app/generators/vulnerability_hunter.py

@@ -295,6 +295,13 @@ NVIDIA_API_KEY = os.environ.get("NVIDIA_API_KEY", "")
 NVIDIA_MODEL = os.environ.get("NVIDIA_MODEL", "deepseek-ai/deepseek-v4-pro")
 NVIDIA_API_URL = "https://integrate.api.nvidia.com/v1/chat/completions"
 
+# PRIMARY AI: Mistral (per the user's request — Mistral runs first)
+MISTRAL_API_KEY = os.environ.get("MISTRAL_API_KEY", "")
+MISTRAL_MODEL = os.environ.get("MISTRAL_MODEL", "mistral-large-latest")
+MISTRAL_API_URL = os.environ.get(
+    "MISTRAL_API_URL", "https://api.mistral.ai/v1/chat/completions"
+)
+
 TABLE_NAME = "vulnerability_hunter_challenges"
 
 # Per-team backoff tracker
@@ -827,6 +834,52 @@ async def _post_with_json_fallback(client, url: str, payload: dict, headers: dic
     return resp
 
 
+async def _try_mistral(prompt: str, system: str, model: str) -> Optional[str]:
+    """Try Mistral API (mistral-large-latest by default).
+
+    Per the user's request, Mistral is the PRIMARY tier for challenge
+    generation — it runs first in the orchestrator. Only on a hard
+    failure (429 / timeout / 5xx / parse) do we fall through to
+    Cloudflare, then Groq, then NVIDIA/DeepSeek, then seed.
+    """
+    if not MISTRAL_API_KEY:
+        return None
+    import httpx as _httpx
+    try:
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {MISTRAL_API_KEY}",
+        }
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+        payload = {
+            "model": model or MISTRAL_MODEL,
+            "messages": messages,
+            "temperature": 0.7,
+            "max_tokens": 4096,
+            "response_format": {"type": "json_object"},
+        }
+        async with _httpx.AsyncClient(timeout=30) as client:
+            resp = await _post_with_json_fallback(client, MISTRAL_API_URL, payload, headers, "mistral")
+        if resp.status_code == 200:
+            data = resp.json()
+            content = data.get("choices", [{}])[0].get("message", {}).get("content")
+            if content:
+                return content
+            print(f"  [mistral] 200 but empty content: {str(data)[:200]}")
+            return None
+        if resp.status_code == 429:
+            print(f"  [mistral] 429 rate-limited")
+        else:
+            print(f"  [mistral] error {resp.status_code}: {resp.text[:200]}")
+        return None
+    except Exception as e:
+        print(f"  [mistral] exception: {type(e).__name__}: {e}")
+        return None
+
+
 async def _try_cloudflare(prompt: str, system: str) -> Optional[str]:
     if not (CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID):
         return None
@@ -844,7 +897,7 @@ async def _try_cloudflare(prompt: str, system: str) -> Optional[str]:
         headers = {"Content-Type": "application/json", "Authorization": f"Bearer {CLOUDFLARE_API_TOKEN}"}
         payload = {**payload_base, "response_format": {"type": "json_object"}}
         try:
-            async with _httpx.AsyncClient(timeout=120) as client:
+            async with _httpx.AsyncClient(timeout=30) as client:
                 resp = await _post_with_json_fallback(client, url, payload, headers, f"cloudflare/{model_name.split('/')[-1]}")
             if resp.status_code == 200:
                 result = resp.json()
@@ -936,6 +989,10 @@ async def _try_nvidia(prompt: str, system: str, model: str) -> Optional[str]:
 
 
 async def _call_ai(prompt: str, system: str = "", model: str = "") -> Optional[str]:
+    print(f"  [ai] Trying Mistral...")
+    r = await _try_mistral(prompt, system, model)
+    if r:
+        return r
     print(f"  [ai] Trying Cloudflare...")
     r = await _try_cloudflare(prompt, system)
     if r:
@@ -948,7 +1005,7 @@ async def _call_ai(prompt: str, system: str = "", model: str = "") -> Optional[s
     r = await _try_nvidia(prompt, system, model)
     if r:
         return r
-    print(f"  [ai] All 3 providers failed")
+    print(f"  [ai] All 4 providers failed")
     return None
 
 
@@ -1136,6 +1193,12 @@ async def get_pool_count(team_role: str) -> int:
 async def _insert_to_db(row: dict) -> bool:
     if not SUPABASE_ANON_KEY or not SUPABASE_URL:
         return False
+    # Enforce the migration 011 CHECK constraint: ``module`` MUST
+    # be the canonical challenge type ('vulnerability-hunter') for
+    # this table — the AI / seed rows used to carry topic-shaped
+    # values like 'web-security', 'secure-coding' or 'cryptography'.
+    from app.core.config import normalize_row_module
+    row = normalize_row_module(TABLE_NAME, row)
     url = f"{SUPABASE_URL}/rest/v1/{TABLE_NAME}"
     headers = supabase_headers(content_type=True)
     headers["Prefer"] = "return=representation"
@@ -1211,7 +1274,15 @@ async def refill_pool(team_role: str, count: int) -> int:
             return True
         return False
 
-    results = await asyncio.gather(*[_gen_one(i) for i in range(target)])
+    # Sequential generation: each challenge is fully generated, validated,
+    # inserted, AND confirmed in the DB before the next one starts. Hitting
+    # the AI in parallel triggers Mistral/CF 429 rate limits.
+    results = []
+    for i in range(target):
+        ok = await _gen_one(i)
+        results.append(ok)
+        # Small backoff between calls to stay well under per-minute quotas.
+        await asyncio.sleep(2.0)
     return sum(1 for r in results if r)
 
 
@@ -1225,12 +1296,13 @@ async def start_pool_watcher(team_role: str):
 
     print(f"[vuln-hunter] Pool watcher started for '{team_role}' (target={POOL_TARGET}, threshold={POOL_THRESHOLD}, batch={POOL_BATCH})")
 
-    # Pre-warm
+    # Pre-warm — tries AI first (Mistral → CF → Groq → NVIDIA),
+    # falls back to seeds only if every AI tier fails.
     try:
         current = await get_pool_count(team_role)
         if current < POOL_TARGET:
             print(f"[vuln-hunter] Pre-warming pool ({current} → {POOL_TARGET})...")
-            added = await _refill_with_seeds_only(team_role, POOL_TARGET - current)
+            added = await refill_pool(team_role, POOL_TARGET - current)
             print(f"[vuln-hunter] Pre-warm done: +{added} challenges")
     except Exception as e:
         print(f"[vuln-hunter] Pre-warm failed: {e}")
@@ -1243,6 +1315,7 @@ async def start_pool_watcher(team_role: str):
                 added = await refill_pool(team_role, POOL_BATCH)
                 print(f"[vuln-hunter] Refill done: +{added} (now {count + added}/{POOL_TARGET})")
                 await asyncio.sleep(2)
+            # else: pool healthy — silent (keep logs clean)
             else:
                 await asyncio.sleep(30)
         except Exception as e:

web_exploitation_generator.py → app/generators/web.py

@@ -310,6 +310,13 @@ NVIDIA_API_KEY = os.environ.get("NVIDIA_API_KEY", "")
 NVIDIA_MODEL = os.environ.get("NVIDIA_MODEL", "deepseek-ai/deepseek-v4-pro")
 NVIDIA_URL = "https://integrate.api.nvidia.com/v1/chat/completions"
 
+# PRIMARY AI: Mistral (per the user's request — Mistral runs first)
+MISTRAL_API_KEY = os.environ.get("MISTRAL_API_KEY", "")
+MISTRAL_MODEL = os.environ.get("MISTRAL_MODEL", "mistral-large-latest")
+MISTRAL_API_URL = os.environ.get(
+    "MISTRAL_API_URL", "https://api.mistral.ai/v1/chat/completions"
+)
+
 FLAG_PREFIX = "CyberArena{"
 
 LAB_PARENT_ORIGIN = "*"   # postMessage target — sandboxed iframe, no real origin concern
@@ -2660,8 +2667,15 @@ def insert_to_db(challenge: Challenge, supabase_url: str = SUPABASE_URL,
         "Content-Type": "application/json",
         "Prefer": "return=minimal",
     }
+    payload = challenge.to_db_row()
+    # Enforce the migration 011 CHECK constraint: ``module`` MUST be
+    # the canonical challenge type ('web') for this table — the
+    # AI / seed rows used to carry topic-shaped values like 'xss',
+    # 'sqli', 'csrf', etc.
+    from app.core.config import normalize_row_module
+    payload = normalize_row_module("web_exploitation_challenges", payload)
     with httpx.Client(timeout=30) as client:
-        r = client.post(url, headers=headers, json=challenge.to_db_row())
+        r = client.post(url, headers=headers, json=payload)
     if r.status_code in (200, 201, 204):
         print(f"✓ Inserted: {challenge.title[:60]}")
         return True
@@ -3474,6 +3488,80 @@ def get_pool_count(team_role: str) -> int:
     except Exception as e:
         print(f"[web_exploitation_generator] get_pool_count error: {e}")
     return 0
+async def ai_generate_scenario_via_mistral(team_role: str, module: str, vuln_type: str,
+                                            difficulty: str, mistral_api_key: str,
+                                            model: str | None = None,
+                                            theme: dict | None = None) -> "ScenarioSpec":
+    """Primary AI: call Mistral (mistral-large-latest) for web scenario generation.
+
+    Per the user's request, Mistral is the first provider tried. Same
+    contract as ``ai_generate_scenario`` (Groq) — returns a
+    ``ScenarioSpec`` and raises on transport errors so the caller
+    can fall back to Groq, then DeepSeek, then seed.
+    """
+    if not mistral_api_key:
+        raise RuntimeError("MISTRAL_API_KEY not configured")
+    model = model or MISTRAL_MODEL
+
+    prompt = WEBEX_SCENARIO_PROMPT.format(
+        team_role=team_role, module=module, vuln_type=vuln_type,
+        difficulty=difficulty,
+        theme_name=(theme or {}).get("name", ""),
+        theme_desc=(theme or {}).get("description", ""),
+    )
+
+    body = {
+        "model": model,
+        "messages": [
+            {"role": "system", "content": "You output valid JSON only. No prose, no markdown fences."},
+            {"role": "user", "content": prompt},
+        ],
+        "temperature": 0.7,
+        "max_tokens": 2500,
+        "response_format": {"type": "json_object"},
+    }
+    async with httpx.AsyncClient(timeout=60) as client:
+        r = await client.post(
+            MISTRAL_API_URL,
+            headers={"Authorization": f"Bearer {mistral_api_key}", "Content-Type": "application/json"},
+            json=body,
+        )
+    if r.status_code == 429:
+        raise RuntimeError("429 from Mistral - rate limit")
+    if r.status_code != 200:
+        raise RuntimeError(f"Mistral HTTP {r.status_code}: {r.text[:200]}")
+
+    content = (r.json().get("choices") or [{}])[0].get("message", {}).get("content", "")
+    if not content:
+        raise RuntimeError("Mistral returned empty content")
+
+    if "```" in content:
+        m = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", content, re.DOTALL)
+        if m:
+            content = m.group(1)
+    content = content.strip()
+    if content.lower().startswith("json"):
+        content = content[4:]
+    content = content.strip().rstrip("`")
+
+    data = _repair_json(content)
+    if not _vuln_type_matches_module(data.get("vuln_type", ""), module):
+        # Reject: AI returned the wrong vuln family for this module.
+        raise ValueError(
+            f"Mistral returned vuln_type={data.get('vuln_type')!r} for module={module!r}"
+        )
+
+    return ScenarioSpec(
+        team_role=team_role,
+        module=module,
+        vuln_type=_coerce_str(data.get("vuln_type"), vuln_type),
+        difficulty=difficulty,
+        title=_coerce_str(data.get("title"), "Untitled"),
+        story=_coerce_str(data.get("story"), ""),
+        task_outline=_coerce_str(data.get("task_outline"), ""),
+        target_input=_coerce_str(data.get("target_input"), "input"),
+        vulnerable_sink=_coerce_str(data.get("vulnerable_sink"), ""),
+    )
 
 
 async def refill_pool(team_role: str, count: int = POOL_BATCH,
@@ -3530,10 +3618,32 @@ async def _refill_pool_unlocked(team_role: str, count: int,
 
         spec = None
         source = "ai"
+        _maybe_try_groq = False
         _maybe_try_deepseek = False
 
+        # ---- 0) Try Mistral for this slot (PRIMARY AI per user request) ----
+        if MISTRAL_API_KEY:
+            try:
+                spec = await ai_generate_scenario_via_mistral(
+                    team_role, module, vuln_type, difficulty, MISTRAL_API_KEY,
+                    theme=theme,
+                )
+                print(f"[webex] Mistral OK: vuln={spec.vuln_type} title={spec.title[:50]}")
+            except Exception as e:
+                err = str(e)
+                if "429" in err or "Rate Limit" in err:
+                    print(f"[webex] Mistral 429 — falling through to Groq")
+                    _maybe_try_groq = True
+                elif "vuln_type=" in err or "empty content" in err:
+                    print(f"[webex] Mistral bad response ({type(e).__name__}) — trying Groq")
+                    _maybe_try_groq = True
+                else:
+                    print(f"[webex] Mistral failed ({team_role}/{module}): {e} — trying Groq")
+                    _maybe_try_groq = True
+            await asyncio.sleep(0.3)
+
         # ---- 1) Try Groq for this slot ----
-        if groq_api_key and not in_backoff:
+        if spec is None and (groq_api_key and not in_backoff or _maybe_try_groq) and groq_api_key and not in_backoff:
             try:
                 spec = await ai_generate_scenario(
                     team_role, module, vuln_type, difficulty, groq_api_key,
@@ -3655,8 +3765,7 @@ async def start_pool_watcher(team_role: str, groq_api_key: str = GROQ_API_KEY) -
                         new_count = count + added
                         print(f"{label} refilled: {count} → {new_count} (target {POOL_TARGET}).")
                         sleep_secs = 5
-                    else:
-                        print(f"{label} pool healthy ({count}/{POOL_TARGET}) — sleeping {IDLE_POLL_SECS}s.")
+                    # else: pool healthy — silent (keep logs clean)
                 await asyncio.sleep(sleep_secs)
             except Exception as e:
                 import traceback

app/main.py

@@ -0,0 +1,117 @@
+"""FastAPI application entry point.
+
+This module builds the ``app`` object that :mod:`main` (the 5-line
+top-level entry) imports and feeds to uvicorn. All real logic lives
+in the subpackages — this file is the wiring diagram.
+"""
+
+# IMPORTANT: load .env BEFORE anything else in the package. This way
+# `python main.py`, `uvicorn app.main:app`, `uvicorn main:app`, or
+# any script that imports `app.main` will all pick up the same
+# environment, regardless of cwd.
+from app._env import load_app_env, assert_critical_env  # noqa: E402
+load_app_env()
+
+import asyncio
+import os
+import sys
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.generators import REGISTRY as GENERATOR_REGISTRY
+
+
+# Force UTF-8 in stdout (Windows Arabic)
+try:
+    sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
+except Exception:
+    pass
+
+
+# --------------------------------------------------------------------------- #
+#  App + middleware                                                           #
+# --------------------------------------------------------------------------- #
+
+app = FastAPI(title="CyberArena Backend")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# --------------------------------------------------------------------------- #
+#  Routers                                                                    #
+# --------------------------------------------------------------------------- #
+
+from app.api import (  # noqa: E402  (import after middleware so order is right)
+    auth as _auth,
+    xp as _xp,
+    leaderboard as _leaderboard,
+    certificates as _certificates,
+    training as _training,
+    terminal as _terminal,
+    onevone as _onevone,
+)
+
+
+def _include_all_routers(app: FastAPI) -> None:
+    app.include_router(_auth.router)
+    app.include_router(_xp.router)
+    app.include_router(_leaderboard.router)
+    app.include_router(_certificates.router)
+    app.include_router(_training.router)
+    app.include_router(_terminal.router)
+    app.include_router(_onevone.router)
+
+
+_include_all_routers(app)
+
+
+# --------------------------------------------------------------------------- #
+#  Background pool watcher                                                    #
+# --------------------------------------------------------------------------- #
+
+async def populate_pool_background() -> None:
+    """Spawn one ``start_pool_watcher(team)`` task per (type, team).
+
+    See AGENTS.md "Pool Architecture" for the per-team registration
+    model. The five registered generators come from
+    :data:`app.generators.REGISTRY`.
+    """
+    await asyncio.sleep(8)  # Gentle wait on startup
+    print("Background pool watcher orchestrator started.")
+    print(f"[main] Active generators: {[name for name, _, _ in GENERATOR_REGISTRY]}")
+
+    for name, gen, teams in GENERATOR_REGISTRY:
+        for team in teams:
+            asyncio.create_task(gen.start_pool_watcher(team))
+
+    # Keep the orchestrator alive
+    while True:
+        await asyncio.sleep(3600)
+
+
+@app.on_event("startup")
+async def startup_event():
+    # Make sure the backend dir is on sys.path so generators (which are
+    # self-contained) and their relative imports keep working.
+    sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    asyncio.create_task(populate_pool_background())
+
+
+# --------------------------------------------------------------------------- #
+#  Environment validation                                                     #
+# --------------------------------------------------------------------------- #
+
+# Run this as soon as a worker imports the module. It only fires once
+# (see app/_env.py::_is_loaded_marker_set) and gives a clear, single-line
+# error instead of a 401 from Supabase ten seconds later.
+assert_critical_env("SUPABASE_URL", "SUPABASE_ANON_KEY")
+
+
+__all__ = ["app", "populate_pool_background"]

app/sandbox/__init__.py

@@ -0,0 +1,19 @@
+"""Sandbox: in-process terminal that the OS-simulator frontend talks to.
+
+A per-challenge temp workdir holds the files declared in the row's
+``files`` JSONB column. Built-in Unix tools (cat, ls, sha256sum, base64,
+…) are reimplemented in Python so they work on Windows. External tools
+(``python``, ``openssl`` …) are executed via subprocess ONLY if the
+challenge row whitelists them.
+"""
+
+from .workdir import get_or_create_workdir, safe_join
+from .tools import shell_builtins
+from .terminal import run_terminal_command
+
+__all__ = [
+    "get_or_create_workdir",
+    "safe_join",
+    "shell_builtins",
+    "run_terminal_command",
+]

app/sandbox/terminal.py

@@ -0,0 +1,103 @@
+"""In-process terminal command runner.
+
+Parses a single command with ``shlex``, runs built-ins via
+:mod:`app.sandbox.tools`, and runs external tools via subprocess — but
+only if the challenge row whitelists them. ``python`` / ``python3`` are
+always allowed so the student can run their own scripts.
+
+Returns the standard ``{stdout, stderr, exitCode}`` dict (plus ``clear``
+for the ``clear`` built-in). Used by :mod:`app.api.terminal`.
+"""
+
+import os
+import shlex
+import subprocess
+from typing import Optional
+
+from .workdir import get_or_create_workdir
+from .tools import shell_builtins
+
+
+# External tools that are always allowed regardless of row whitelist.
+ALWAYS_ALLOWED = {"python", "python3", "py"}
+
+
+def parse_command(command: str) -> Optional[list[str]]:
+    """Return shlex-split tokens or None on a parse error."""
+    try:
+        return shlex.split(command)
+    except ValueError:
+        return None
+
+
+async def run_terminal_command(team_role: str, challenge_id: str, command: str) -> dict:
+    """Execute a terminal command in the challenge's sandbox for real."""
+    command = (command or "").strip()
+
+    if not command:
+        return {"stdout": "", "stderr": "❌ أمر فارغ", "exitCode": 1}
+    if not challenge_id:
+        return {"stdout": "", "stderr": "❌ challengeId مفقود", "exitCode": 1}
+
+    workdir, row = await get_or_create_workdir(team_role, challenge_id)
+    allowed = (row or {}).get("tools_whitelist") or []
+
+    parts = parse_command(command)
+    if parts is None:
+        return {"stdout": "", "stderr": "❌ صيغة الأمر غير صحيحة", "exitCode": 2}
+    if not parts:
+        return {"stdout": "", "stderr": "", "exitCode": 0}
+
+    tool = parts[0]
+
+    # submit is handled client-side already; refuse here to avoid confusion
+    if tool == "submit":
+        return {
+            "stdout": "",
+            "stderr": "❌ استخدم نموذج الإجابة في اللوحة، أو اكتب submit في الـ terminal بعد ربطه بالـ backend.",
+            "exitCode": 1,
+        }
+
+    # Built-ins
+    if tool in {"cat", "ls", "pwd", "echo", "whoami", "clear", "help",
+                "sha256sum", "md5sum", "sha1sum", "base64", "xxd", "tr"}:
+        result = shell_builtins(parts, workdir)
+        if result is not None:
+            return result
+
+    # Whitelist check (python/python3 are always allowed for user-authored scripts)
+    if tool not in allowed and tool not in ALWAYS_ALLOWED:
+        return {
+            "stdout": "",
+            "stderr": (
+                f"❌ '{tool}' غير مسموح في هذا التحدي.\n"
+                f"الأدوات المسموحة: {', '.join(allowed) if allowed else '(لا توجد)'}"
+            ),
+            "exitCode": 126,
+        }
+
+    # Run real subprocess with UTF-8 forced (Arabic in child process output)
+    try:
+        env = os.environ.copy()
+        env["PYTHONIOENCODING"] = "utf-8"
+        env["PYTHONUTF8"] = "1"
+        proc = subprocess.run(
+            parts,
+            cwd=workdir,
+            capture_output=True,
+            timeout=8,
+            env=env,
+        )
+        stdout = (proc.stdout or b"").decode("utf-8", errors="replace")
+        stderr = (proc.stderr or b"").decode("utf-8", errors="replace")
+        return {
+            "stdout": stdout[:8000],
+            "stderr": stderr[:3000],
+            "exitCode": proc.returncode,
+        }
+    except FileNotFoundError:
+        return {"stdout": "", "stderr": f"❌ '{tool}' غير مثبت على خادم الساندبوكس.", "exitCode": 127}
+    except subprocess.TimeoutExpired:
+        return {"stdout": "", "stderr": "⏱️ انتهت المهلة (8 ثوانٍ). قد يكون الأمر يدور في حلقة لا نهائية.", "exitCode": 124}
+    except Exception as e:
+        return {"stdout": "", "stderr": f"❌ خطأ: {e}", "exitCode": 1}

app/sandbox/tools.py

@@ -0,0 +1,115 @@
+"""Built-in Unix tools reimplemented in Python so they work on Windows.
+
+These are what the OS simulator uses for cat / ls / sha256sum / base64 /
+xxd / tr / … . External tools (python, openssl, …) are executed via
+subprocess from :mod:`app.sandbox.terminal`.
+"""
+
+import base64
+import binascii
+import hashlib
+import os
+from typing import Optional
+
+from app.core.constants import HELP_TEXT
+
+
+def shell_builtins(args: list[str], workdir: str) -> Optional[dict]:
+    """Run a built-in command. Returns a ``{stdout, stderr, exitCode}``
+    result dict, or ``None`` if the tool is not a built-in (caller should
+    fall through to subprocess)."""
+    tool = args[0] if args else ""
+    rest = args[1:]
+    try:
+        if tool == "cat":
+            if not rest:
+                return {"stdout": "", "stderr": "cat: missing filename", "exitCode": 1}
+            out, err = [], ""
+            for fname in rest:
+                p = os.path.join(workdir, fname.lstrip("/\\").replace("..", "_"))
+                if not os.path.isfile(p):
+                    err += f"cat: {fname}: No such file\n"
+                    continue
+                with open(p, "r", encoding="utf-8", errors="replace") as f:
+                    out.append(f.read())
+            return {"stdout": "\n".join(out), "stderr": err, "exitCode": 0 if not err else 1}
+        if tool == "ls":
+            entries = sorted(os.listdir(workdir))
+            lines = []
+            for n in entries:
+                if n.startswith("."):
+                    continue
+                p = os.path.join(workdir, n)
+                if os.path.isdir(p):
+                    lines.append(f"<DIR>          {n}")
+                else:
+                    lines.append(f"               {n}")
+            return {"stdout": "\n".join(lines), "stderr": "", "exitCode": 0}
+        if tool == "pwd":
+            return {"stdout": workdir, "stderr": "", "exitCode": 0}
+        if tool == "echo":
+            return {"stdout": " ".join(rest), "stderr": "", "exitCode": 0}
+        if tool == "whoami":
+            return {"stdout": os.environ.get("USERNAME") or os.environ.get("USER") or "student", "stderr": "", "exitCode": 0}
+        if tool == "clear":
+            return {"stdout": "\x1b[2J\x1b[H", "stderr": "", "exitCode": 0, "clear": True}
+        if tool == "help":
+            return {"stdout": HELP_TEXT, "stderr": "", "exitCode": 0}
+        if tool in ("sha256sum", "md5sum", "sha1sum"):
+            algo = {"sha256sum": "sha256", "md5sum": "md5", "sha1sum": "sha1"}[tool]
+            if not rest:
+                return {"stdout": "", "stderr": f"{tool}: missing filename", "exitCode": 1}
+            out, err = [], ""
+            for fname in rest:
+                p = os.path.join(workdir, fname.lstrip("/\\").replace("..", "_"))
+                if not os.path.isfile(p):
+                    err += f"{tool}: {fname}: No such file\n"
+                    continue
+                with open(p, "rb") as f:
+                    h = hashlib.new(algo, f.read()).hexdigest()
+                out.append(f"{h}  {fname}")
+            return {"stdout": "\n".join(out), "stderr": err, "exitCode": 0 if not err else 1}
+        if tool == "base64":
+            decode = "-d" in rest
+            args2 = [a for a in rest if a != "-d"]
+            if not args2:
+                import sys
+                data = sys.stdin.read() if not sys.stdin.isatty() else b""
+                if decode:
+                    return {"stdout": base64.b64decode(data).decode("utf-8", "replace"), "stderr": "", "exitCode": 0}
+                return {"stdout": base64.b64encode(data).decode(), "stderr": "", "exitCode": 0}
+            out, err = [], ""
+            for fname in args2:
+                p = os.path.join(workdir, fname.lstrip("/\\").replace("..", "_"))
+                if not os.path.isfile(p):
+                    err += f"base64: {fname}: No such file\n"
+                    continue
+                with open(p, "rb") as f:
+                    data = f.read()
+                if decode:
+                    out.append(base64.b64decode(data).decode("utf-8", "replace"))
+                else:
+                    out.append(base64.b64encode(data).decode())
+            return {"stdout": "\n".join(out), "stderr": err, "exitCode": 0 if not err else 1}
+        if tool == "xxd":
+            if not rest:
+                return {"stdout": "", "stderr": "xxd: missing filename", "exitCode": 1}
+            p = os.path.join(workdir, rest[0].lstrip("/\\").replace("..", "_"))
+            if not os.path.isfile(p):
+                return {"stdout": "", "stderr": f"xxd: {rest[0]}: No such file", "exitCode": 1}
+            with open(p, "rb") as f:
+                data = f.read()
+            return {"stdout": binascii.hexlify(data).decode(), "stderr": "", "exitCode": 0}
+        if tool == "tr":
+            if len(rest) < 2:
+                return {"stdout": "", "stderr": "tr: usage: tr SET1 SET2", "exitCode": 1}
+            set1, set2 = rest[0], rest[1]
+            if len(rest) > 2:
+                src = " ".join(rest[2:])
+                for a, b in zip(set1, set2):
+                    src = src.replace(a, b)
+                return {"stdout": src, "stderr": "", "exitCode": 0}
+            return {"stdout": "", "stderr": "tr: no input", "exitCode": 1}
+    except Exception as e:
+        return {"stdout": "", "stderr": f"{tool}: {e}", "exitCode": 1}
+    return None  # not a builtin

app/sandbox/workdir.py

@@ -0,0 +1,72 @@
+"""Per-challenge temp workdir for the OS simulator.
+
+Each (team_role, challenge_id) tuple gets its own tempdir; the row's
+``files`` JSONB is materialized into real files on first access. The
+workdir is cached in-process so the user can `cd` / write scripts
+across multiple terminal calls.
+"""
+
+import os
+import tempfile
+import base64
+from typing import Optional, Tuple
+
+from app.services.supabase_service import fetch_scenario_by_id
+
+
+# In-process cache: key -> (workdir_path, last_loaded_row_dict)
+_workdirs: dict[str, str] = {}
+_last_loaded_row: dict[str, dict] = {}
+
+
+async def get_or_create_workdir(team_role: str, challenge_id: str) -> Tuple[str, dict]:
+    """Return (workdir_path, challenge_row) — cached per challenge.
+
+    If the row isn't in Supabase (e.g. ad-hoc training mode), an empty
+    workdir is created and an empty row dict is returned.
+    """
+    key = f"{team_role}:{challenge_id}"
+    if key in _workdirs and os.path.isdir(_workdirs[key]):
+        return _workdirs[key], _last_loaded_row.get(key, {})
+
+    row: Optional[dict] = None
+    if challenge_id:
+        try:
+            row = await fetch_scenario_by_id(team_role, challenge_id)
+        except Exception:
+            row = None
+    if row is None:
+        workdir = tempfile.mkdtemp(prefix=f"ca_{team_role}_{challenge_id[:8]}_")
+        _workdirs[key] = workdir
+        return workdir, {}
+
+    workdir = tempfile.mkdtemp(prefix=f"ca_{team_role}_{challenge_id[:8]}_")
+    files = row.get("files") or {}
+    for filename, b64 in files.items():
+        # Sanitize: /etc/shadow -> etc/shadow inside workdir
+        clean = filename.lstrip("/\\").replace("..", "_").replace("\\", "/")
+        target = os.path.join(workdir, clean)
+        os.makedirs(os.path.dirname(target) or workdir, exist_ok=True)
+        try:
+            data = base64.b64decode(b64)
+            with open(target, "wb") as f:
+                f.write(data)
+        except Exception:
+            pass
+    with open(os.path.join(workdir, ".challenge_id"), "w") as f:
+        f.write(challenge_id)
+    _workdirs[key] = workdir
+    _last_loaded_row[key] = row
+    return workdir, row
+
+
+def safe_join(workdir: str, filename: str) -> str:
+    """Resolve ``filename`` inside ``workdir``; block path traversal."""
+    clean = (filename or "").lstrip("/\\").replace("..", "_").replace("\\", "/")
+    if not clean:
+        raise ValueError("empty filename")
+    target = os.path.normpath(os.path.join(workdir, clean))
+    workdir_abs = os.path.normpath(workdir)
+    if not target.startswith(workdir_abs):
+        raise ValueError("path traversal blocked")
+    return target

app/services/__init__.py

@@ -0,0 +1,119 @@
+"""Service layer: business logic and external I/O.
+
+Modules in this package talk to Supabase, AI providers, and the file
+system. They never import from :mod:`app.api` (the routers depend on
+them, not the other way around).
+"""
+
+from . import (
+    supabase_service,
+    challenge_loader,
+    scenario_service,
+    evaluator,
+    completion_service,
+    certificate_service,
+    file_storage,
+)
+
+from .supabase_service import (
+    supabase_headers,
+    scenario_table,
+    get_supabase_scenario_count,
+    fetch_scenario_by_id,
+    fetch_random_scenario_from_supabase,
+    delete_scenario_from_supabase,
+    insert_scenario_to_supabase,
+)
+from .challenge_loader import (
+    map_encryption_row_to_training,
+    map_webex_row_to_training,
+    map_code_fixing_row_to_training,
+    map_log_analysis_row_to_training,
+    map_vuln_hunter_row_to_training,
+)
+from .scenario_service import (
+    generate_scenario_from_groq,
+    generate_challenge_from_scenario,
+    generate_challenge_from_groq,
+    generate_and_store_scenario,
+    handle_background_replacement,
+    map_scenario_to_list_item,
+    attach_scenario_metadata,
+)
+from .evaluator import (
+    evaluate_training,
+    evaluate_web_exploitation,
+    evaluate_code_fix,
+    evaluate_log_analysis,
+    evaluate_vuln_hunter,
+    ai_evaluate_code_fix,
+)
+from .completion_service import (
+    record_user_completion,
+    count_completions,
+)
+from .certificate_service import (
+    handle_certificates,
+    download_certificate_pdf,
+    verify_certificate,
+    cert_progress,
+    make_verify_code,
+    build_cert_title,
+    category_label,
+)
+from .file_storage import (
+    upload_challenge_file,
+)
+
+__all__ = [
+    # modules
+    "supabase_service",
+    "challenge_loader",
+    "scenario_service",
+    "evaluator",
+    "completion_service",
+    "certificate_service",
+    "file_storage",
+    # supabase
+    "supabase_headers",
+    "scenario_table",
+    "get_supabase_scenario_count",
+    "fetch_scenario_by_id",
+    "fetch_random_scenario_from_supabase",
+    "delete_scenario_from_supabase",
+    "insert_scenario_to_supabase",
+    # challenge_loader
+    "map_encryption_row_to_training",
+    "map_webex_row_to_training",
+    "map_code_fixing_row_to_training",
+    "map_log_analysis_row_to_training",
+    "map_vuln_hunter_row_to_training",
+    # scenario_service
+    "generate_scenario_from_groq",
+    "generate_challenge_from_scenario",
+    "generate_challenge_from_groq",
+    "generate_and_store_scenario",
+    "handle_background_replacement",
+    "map_scenario_to_list_item",
+    "attach_scenario_metadata",
+    # evaluator
+    "evaluate_training",
+    "evaluate_web_exploitation",
+    "evaluate_code_fix",
+    "evaluate_log_analysis",
+    "evaluate_vuln_hunter",
+    "ai_evaluate_code_fix",
+    # completion
+    "record_user_completion",
+    "count_completions",
+    # certificate
+    "handle_certificates",
+    "download_certificate_pdf",
+    "verify_certificate",
+    "cert_progress",
+    "make_verify_code",
+    "build_cert_title",
+    "category_label",
+    # file_storage
+    "upload_challenge_file",
+]

app/services/certificate_service.py

@@ -0,0 +1,464 @@
+"""Certificate service: issuance, verification, PDF rendering."""
+
+import io
+import os
+import random
+import re
+import tempfile
+from datetime import datetime
+from typing import Optional
+
+import httpx
+from fastapi import HTTPException
+from fastapi.responses import Response
+
+from app.core.constants import CERT_REQUIRED_COMPLETIONS, CERT_VERIFY_BASE_URL
+from app.core.config import SUPABASE_URL, SUPABASE_ANON_KEY
+from app.services.supabase_service import supabase_headers
+from app.services.completion_service import count_completions
+
+
+# --------------------------------------------------------------------------- #
+#  Verifiability                                                              #
+# --------------------------------------------------------------------------- #
+
+def make_verify_code(user_id: str) -> str:
+    """Generate a short, human-friendly verify code (8-10 chars)."""
+    alphabet = "ABCDEFGHJKMNPQRSTUVWXYZ23456789"  # no 0/1/I/O confusion
+    suffix = "".join(random.choice(alphabet) for _ in range(4))
+    head = re.sub(r"[^a-f0-9]", "", (user_id or "").lower())[:6].upper()
+    if len(head) < 4:
+        head = (head + "USER1")[:6]
+    return f"APEX-{head}-{suffix}"
+
+
+def build_cert_title(category: str) -> str:
+    cat = (category or "").strip().lower()
+    mapping = {
+        "vulnerability-hunter": "Cybersecurity Vulnerability Hunter",
+        "code-fixing": "Secure Code Specialist",
+        "log-analysis": "SOC Log Analysis Operator",
+        "web": "Web Application Security",
+        "crypto": "Applied Cryptography",
+    }
+    return mapping.get(cat, category or "Cybersecurity")
+
+
+def category_label(category: str, lang: str = "en") -> str:
+    cat = (category or "").strip().lower()
+    ar_map = {
+        "vulnerability-hunter": "صياد الثغرات",
+        "code-fixing": "إصلاح الأكواد",
+        "log-analysis": "تحليل السجلات",
+        "web": "أمن الويب",
+        "crypto": "التشفير",
+    }
+    en_map = {
+        "vulnerability-hunter": "Vulnerability Hunter",
+        "code-fixing": "Code Fixing",
+        "log-analysis": "Log Analysis",
+        "web": "Web Security",
+        "crypto": "Cryptography",
+    }
+    return (ar_map if lang == "ar" else en_map).get(cat, category or "")
+
+
+def _format_date_en(dt_value) -> str:
+    if not dt_value:
+        return ""
+    try:
+        if isinstance(dt_value, str):
+            s = dt_value.replace("Z", "+00:00")
+            dt = datetime.fromisoformat(s)
+        else:
+            dt = dt_value
+        return dt.strftime("%B %d, %Y")
+    except Exception:
+        return str(dt_value)[:10]
+
+
+def _format_date_ar(dt_value) -> str:
+    if not dt_value:
+        return ""
+    try:
+        if isinstance(dt_value, str):
+            s = dt_value.replace("Z", "+00:00")
+            dt = datetime.fromisoformat(s)
+        else:
+            dt = dt_value
+        months = ["يناير", "فبراير", "مارس", "أبريل", "مايو", "يونيو",
+                  "يوليو", "أغسطس", "سبتمبر", "أكتوبر", "نوفمبر", "ديسمبر"]
+        return f"{dt.day} {months[dt.month-1]} {dt.year}"
+    except Exception:
+        return str(dt_value)[:10]
+
+
+# --------------------------------------------------------------------------- #
+#  PDF generation                                                             #
+# --------------------------------------------------------------------------- #
+
+def build_certificate_pdf(
+    user_name: str,
+    category: str,
+    title: str,
+    issue_date: str,
+    verify_code: str,
+    cert_id: str,
+    lang: str = "en",
+) -> bytes:
+    """Render the certificate as a real PDF (landscape A4) using reportlab.
+
+    Layout (LTR, Latin-friendly typography for English copy, Arabic for ar):
+      - top brand bar
+      - big title "CERTIFICATE OF COMPLETION" / "شهادة إتمام"
+      - intro line
+      - student name (large)
+      - "has successfully completed" / "أكمل بنجاح"
+      - category name (large)
+      - summary line
+      - footer: QR code (left), date (middle), signature (right)
+    """
+    from reportlab.lib.pagesizes import landscape, A4
+    from reportlab.lib import colors
+    from reportlab.lib.units import mm
+    from reportlab.pdfgen import canvas
+    import qrcode
+    from qrcode.image.pil import PilImage
+
+    width, height = landscape(A4)
+    buf = io.BytesIO()
+    c = canvas.Canvas(buf, pagesize=landscape(A4))
+
+    # ---- Background (cream / parchment) ----
+    c.setFillColorRGB(0.99, 0.98, 0.94)
+    c.rect(0, 0, width, height, fill=1, stroke=0)
+
+    # ---- Outer border (double) ----
+    c.setStrokeColorRGB(0.13, 0.18, 0.32)
+    c.setLineWidth(4)
+    c.rect(12 * mm, 12 * mm, width - 24 * mm, height - 24 * mm)
+    c.setLineWidth(1.2)
+    c.rect(16 * mm, 16 * mm, width - 32 * mm, height - 32 * mm)
+
+    # ---- Corner ornaments ----
+    c.setFillColorRGB(0.13, 0.18, 0.32)
+    for cx, cy in [
+        (18 * mm, height - 18 * mm),
+        (width - 18 * mm, height - 18 * mm),
+        (18 * mm, 18 * mm),
+        (width - 18 * mm, 18 * mm),
+    ]:
+        c.circle(cx, cy, 3 * mm, fill=1, stroke=0)
+        c.setStrokeColorRGB(0.92, 0.72, 0.18)
+        c.setLineWidth(1.4)
+        c.circle(cx, cy, 5 * mm, fill=0, stroke=1)
+        c.setStrokeColorRGB(0.13, 0.18, 0.32)
+        c.setLineWidth(4)
+
+    # ---- Top brand bar ----
+    c.setFillColorRGB(0.13, 0.18, 0.32)
+    c.rect(0, height - 26 * mm, width, 14 * mm, fill=1, stroke=0)
+    c.setFillColorRGB(0.92, 0.72, 0.18)
+    c.rect(0, height - 27 * mm, width, 1.5 * mm, fill=1, stroke=0)
+    c.setFillColorRGB(1, 1, 1)
+    c.setFont("Helvetica-Bold", 22)
+    c.drawString(20 * mm, height - 21 * mm, "◆ CYBERARENA")
+    c.setFont("Helvetica", 11)
+    label = "ALPHA TEAM · CYBERSECURITY TRAINING"
+    c.drawRightString(width - 20 * mm, height - 21 * mm, label)
+
+    # ---- Title ----
+    if lang == "ar":
+        title_text = "شهادة إتمام"
+        subtitle_text = "CERTIFICATE OF COMPLETION"
+    else:
+        title_text = "CERTIFICATE OF COMPLETION"
+        subtitle_text = ""
+    c.setFillColorRGB(0.13, 0.18, 0.32)
+    c.setFont("Helvetica-Bold", 38)
+    c.drawCentredString(width / 2, height - 56 * mm, title_text)
+    if subtitle_text:
+        c.setFillColorRGB(0.45, 0.45, 0.55)
+        c.setFont("Helvetica", 12)
+        c.drawCentredString(width / 2, height - 64 * mm, subtitle_text)
+
+    # ---- Intro ----
+    if lang == "ar":
+        intro = "نشهد بأن الطالب"
+    else:
+        intro = "This is to certify that"
+    c.setFillColorRGB(0.25, 0.25, 0.3)
+    c.setFont("Helvetica", 14)
+    c.drawCentredString(width / 2, height - 80 * mm, intro)
+
+    # ---- Student name ----
+    c.setFillColorRGB(0.13, 0.18, 0.32)
+    c.setFont("Helvetica-Bold", 30)
+    c.drawCentredString(width / 2, height - 96 * mm, (user_name or "Trainee")[:60])
+
+    # ---- Underline ----
+    c.setStrokeColorRGB(0.92, 0.72, 0.18)
+    c.setLineWidth(1.4)
+    name_w = c.stringWidth((user_name or "Trainee")[:60], "Helvetica-Bold", 30)
+    c.line(width/2 - name_w/2 - 4, height - 100 * mm, width/2 + name_w/2 + 4, height - 100 * mm)
+    c.setStrokeColorRGB(0.13, 0.18, 0.32)
+    c.setLineWidth(4)
+
+    # ---- Body line ----
+    if lang == "ar":
+        body = "قد أتمّ بنجاح جميع التحديات العملية في مجال:"
+    else:
+        body = "has successfully completed all interactive challenges and labs in:"
+    c.setFillColorRGB(0.25, 0.25, 0.3)
+    c.setFont("Helvetica", 13)
+    c.drawCentredString(width / 2, height - 116 * mm, body)
+
+    # ---- Category ----
+    cat_label = category_label(category, lang=lang)
+    c.setFillColorRGB(0.92, 0.45, 0.10)
+    c.setFont("Helvetica-Bold", 24)
+    c.drawCentredString(width / 2, height - 132 * mm, cat_label)
+
+    # ---- Sub-summary ----
+    if lang == "ar":
+        sub = f"المستوى: {title}"
+    else:
+        sub = f"Specialization: {title}"
+    c.setFillColorRGB(0.35, 0.35, 0.4)
+    c.setFont("Helvetica-Oblique", 11)
+    c.drawCentredString(width / 2, height - 142 * mm, sub)
+
+    # ---- QR code (left) ----
+    qr_payload = (CERT_VERIFY_BASE_URL or "https://cyberarena.app/verify") + "/" + verify_code
+    qr = qrcode.QRCode(box_size=4, border=1)
+    qr.add_data(qr_payload)
+    qr.make(fit=True)
+    qr_img = qr.make_image(fill_color="#1d2440", back_color="white", image_factory=PilImage)
+    qr_path = os.path.join(tempfile.gettempdir(), f"ca_qr_{verify_code.replace(' ', '_')}.png")
+    qr_img.save(qr_path, format="PNG")
+    qr_size = 28 * mm
+    qr_x = 32 * mm
+    qr_y = 32 * mm
+    c.drawImage(
+        qr_path,
+        qr_x,
+        qr_y,
+        width=qr_size,
+        height=qr_size,
+        preserveAspectRatio=True,
+        mask="auto",
+    )
+    c.setFillColorRGB(0.13, 0.18, 0.32)
+    c.setFont("Helvetica-Bold", 9)
+    qr_caption = "SCAN TO VERIFY" if lang == "en" else "امسح للتحقق"
+    c.drawCentredString(qr_x + qr_size / 2, qr_y - 4 * mm, qr_caption)
+    c.setFont("Helvetica", 8)
+    c.setFillColorRGB(0.35, 0.35, 0.4)
+    c.drawCentredString(qr_x + qr_size / 2, qr_y - 7.5 * mm, verify_code)
+
+    # ---- Date (center) ----
+    date_str = (_format_date_en(issue_date) if lang == "en" else _format_date_ar(issue_date))
+    if not date_str:
+        date_str = "—"
+    cx = width / 2
+    c.setFillColorRGB(0.13, 0.18, 0.32)
+    c.setFont("Helvetica-Bold", 11)
+    c.drawCentredString(cx, 36 * mm, "ISSUE DATE" if lang == "en" else "تاريخ الإصدار")
+    c.setFont("Helvetica", 12)
+    c.setFillColorRGB(0.25, 0.25, 0.3)
+    c.drawCentredString(cx, 28 * mm, date_str)
+    c.setStrokeColorRGB(0.13, 0.18, 0.32)
+    c.setLineWidth(0.6)
+    c.line(cx - 22 * mm, 24 * mm, cx + 22 * mm, 24 * mm)
+    c.setFillColorRGB(0.45, 0.45, 0.55)
+    c.setFont("Helvetica", 9)
+    sign_label = "Alpha Team Academic Board" if lang == "en" else "المجلس الأكاديمي · فريق ألفا"
+    c.drawCentredString(cx, 20 * mm, sign_label)
+
+    # ---- Certificate ID (right) ----
+    rx = width - 60 * mm
+    c.setFillColorRGB(0.13, 0.18, 0.32)
+    c.setFont("Helvetica-Bold", 9)
+    c.drawString(rx, 44 * mm, "CERTIFICATE ID" if lang == "en" else "رقم الشهادة")
+    c.setFont("Helvetica", 9)
+    c.setFillColorRGB(0.25, 0.25, 0.3)
+    c.drawString(rx, 39 * mm, str(cert_id)[:36])
+    c.setFont("Helvetica-Bold", 9)
+    c.setFillColorRGB(0.13, 0.18, 0.32)
+    c.drawString(rx, 32 * mm, "VERIFICATION" if lang == "en" else "رمز التحقق")
+    c.setFont("Helvetica", 9)
+    c.setFillColorRGB(0.25, 0.25, 0.3)
+    c.drawString(rx, 27 * mm, verify_code)
+
+    c.showPage()
+    c.save()
+    return buf.getvalue()
+
+
+# --------------------------------------------------------------------------- #
+#  HTTP handlers (called by the api/certificates router)                      #
+# --------------------------------------------------------------------------- #
+
+async def handle_certificates(req) -> dict:
+    headers = {
+        "apikey": SUPABASE_ANON_KEY,
+        "Authorization": f"Bearer {SUPABASE_ANON_KEY}",
+        "Content-Type": "application/json",
+        "Prefer": "return=representation",
+    }
+
+    if req.action == "list":
+        url = f"{SUPABASE_URL}/rest/v1/certificates?select=*"
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(url, headers=headers)
+            if resp.status_code != 200:
+                raise HTTPException(status_code=resp.status_code, detail="Failed to fetch certificates")
+            certs = resp.json()
+        user_certs = [c for c in certs if str(c.get("user_id")) == str(req.user_id)]
+        return {"certificates": user_certs}
+
+    if req.action == "issue":
+        async with httpx.AsyncClient() as client:
+            # 1) already-issued?
+            check_url = (
+                f"{SUPABASE_URL}/rest/v1/certificates?user_id=eq.{req.user_id}"
+                f"&category=eq.{req.category}&select=*&limit=1"
+            )
+            check_resp = await client.get(check_url, headers=headers)
+            if check_resp.status_code == 200 and check_resp.json():
+                return {"status": "already_issued", "certificate": check_resp.json()[0]}
+
+            # 2) Eligibility
+            completions = await count_completions(req.user_id, req.category or "")
+            if completions < CERT_REQUIRED_COMPLETIONS:
+                return {
+                    "status": "not_eligible",
+                    "error": "completion_threshold_not_met",
+                    "message": (
+                        f"You need {CERT_REQUIRED_COMPLETIONS} completed challenges "
+                        f"in {req.category} to earn this certificate "
+                        f"(you currently have {completions})."
+                    ),
+                    "completions": completions,
+                    "required": CERT_REQUIRED_COMPLETIONS,
+                }
+
+            # 3) User name
+            user_name = ""
+            try:
+                users_resp = await client.get(
+                    f"{SUPABASE_URL}/rest/v1/users?id=eq.{req.user_id}&select=name&limit=1",
+                    headers=headers,
+                )
+                if users_resp.status_code == 200 and users_resp.json():
+                    user_name = (users_resp.json()[0].get("name") or "").strip()
+            except Exception:
+                pass
+
+            # 4) Issue
+            verify_code = req.verify_code or make_verify_code(req.user_id)
+            category = req.category or "general"
+            payload = {
+                "user_id": req.user_id,
+                "user_name": user_name,
+                "category": category,
+                "title": (
+                    req.details.get("title")
+                    if isinstance(req.details, dict) and req.details.get("title")
+                    else build_cert_title(category)
+                ),
+                "verify_code": verify_code,
+                "issue_date": datetime.utcnow().isoformat() + "Z",
+                "details": req.details or {"issue_reason": "50 challenges completed"},
+            }
+            resp = await client.post(
+                f"{SUPABASE_URL}/rest/v1/certificates",
+                headers={**headers, "Prefer": "return=representation"},
+                json=payload,
+            )
+            if resp.status_code not in (200, 201):
+                raise HTTPException(
+                    status_code=resp.status_code,
+                    detail=f"Failed to issue certificate: {resp.text[:200]}",
+                )
+            certs = resp.json()
+            return {"status": "issued", "certificate": certs[0] if certs else {}}
+
+    raise HTTPException(status_code=400, detail="Invalid action")
+
+
+async def download_certificate_pdf(cert_id: str, lang: str = "en") -> Response:
+    if not SUPABASE_URL or not SUPABASE_ANON_KEY:
+        raise HTTPException(status_code=503, detail="Supabase not configured")
+    url = f"{SUPABASE_URL}/rest/v1/certificates?id=eq.{cert_id}&select=*&limit=1"
+    try:
+        async with httpx.AsyncClient(timeout=15) as client:
+            r = await client.get(url, headers=supabase_headers())
+            if r.status_code != 200:
+                raise HTTPException(status_code=502, detail=f"Supabase error: {r.text[:200]}")
+            rows = r.json()
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=502, detail=str(e))
+    if not rows:
+        raise HTTPException(status_code=404, detail="الشهادة غير موجودة / Certificate not found")
+    cert = rows[0]
+
+    pdf_bytes = build_certificate_pdf(
+        user_name=cert.get("user_name") or "",
+        category=cert.get("category") or "",
+        title=cert.get("title") or build_cert_title(cert.get("category", "")),
+        issue_date=cert.get("issue_date") or cert.get("issued_at") or "",
+        verify_code=cert.get("verify_code") or "",
+        cert_id=cert.get("id") or cert_id,
+        lang=lang if lang in ("ar", "en") else "en",
+    )
+    cat = (cert.get("category") or "CyberArena").replace(" ", "_")
+    fname = f"CyberArena-Certificate-{cat}-{cert.get('verify_code', cert_id)[:20]}.pdf"
+    return Response(
+        content=pdf_bytes,
+        media_type="application/pdf",
+        headers={
+            "Content-Disposition": f'attachment; filename="{fname}"',
+            "Cache-Control": "no-store",
+        },
+    )
+
+
+async def verify_certificate(verify_code: str) -> dict:
+    if not SUPABASE_URL or not SUPABASE_ANON_KEY:
+        raise HTTPException(status_code=503, detail="Supabase not configured")
+    url = f"{SUPABASE_URL}/rest/v1/certificates?verify_code=eq.{verify_code}&select=*&limit=1"
+    try:
+        async with httpx.AsyncClient(timeout=15) as client:
+            r = await client.get(url, headers=supabase_headers())
+            if r.status_code != 200:
+                raise HTTPException(status_code=502, detail=f"Supabase error: {r.text[:200]}")
+            rows = r.json()
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=502, detail=str(e))
+    if not rows:
+        return {"valid": False, "verify_code": verify_code, "message": "Certificate not found"}
+    c = rows[0]
+    return {
+        "valid": True,
+        "verify_code": c.get("verify_code"),
+        "certificate_id": c.get("id"),
+        "user_name": c.get("user_name"),
+        "category": c.get("category"),
+        "title": c.get("title") or build_cert_title(c.get("category", "")),
+        "issue_date": c.get("issue_date") or c.get("issued_at"),
+    }
+
+
+async def cert_progress(user_id: str, category: str) -> dict:
+    n = await count_completions(user_id, category)
+    return {
+        "category": category,
+        "completions": n,
+        "required": CERT_REQUIRED_COMPLETIONS,
+        "ready": n >= CERT_REQUIRED_COMPLETIONS,
+    }

app/services/challenge_loader.py

@@ -0,0 +1,206 @@
+"""Map raw Supabase rows to the ``TrainingData`` shape the frontend expects.
+
+Each ``_map_*_row_to_training(row, team_role) -> dict`` function knows
+the columns of one challenge table and returns a consistent object so
+the frontend editor can render any challenge type.
+"""
+
+import base64 as _b64
+
+
+_CODE_LANG_BY_EXT = {
+    "html": "html", "js": "javascript", "ts": "typescript",
+    "py": "python", "json": "json", "csv": "text",
+    "pem": "text", "log": "text", "txt": "text", "bin": "binary",
+}
+
+
+def _infer_code_language(filename, team_role: str) -> str:
+    if not filename:
+        return "text"
+    ext = filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
+    return _CODE_LANG_BY_EXT.get(ext, "text")
+
+
+def map_encryption_row_to_training(row: dict, team_role: str) -> dict:
+    """Map a row from ``encryption_challenges`` to TrainingData."""
+    files = row.get("files") or {}
+    file_meta = row.get("file_metadata") or {}
+    first_filename = next(iter(files), None)
+    code = ""
+    if first_filename:
+        try:
+            code = _b64.b64decode(files[first_filename]).decode("utf-8", errors="replace")
+        except Exception:
+            code = ""
+
+    return {
+        "id": row.get("id"),
+        "scenarioId": row.get("id"),
+        "title": row.get("title", ""),
+        "story": row.get("story", ""),
+        # Challenge type is always 'crypto' for rows coming from
+        # encryption_challenges — the ``module`` column is no longer
+        # authoritative after the 011 normalization migration.
+        "type": "crypto",
+        "topic": row.get("topic") or row.get("module", "encryption-basics"),
+        "task": row.get("task_outline", ""),
+        "code": code,
+        "codeLanguage": _infer_code_language(first_filename, team_role),
+        "htmlPreview": code if (first_filename or "").endswith(".html") else None,
+        "logData": code if (first_filename or "").endswith((".log", ".txt")) else None,
+        "configData": code if (first_filename or "").endswith((".json", ".csv", ".pem")) else None,
+        "vulnerabilityLocation": None,
+        "hints": row.get("hints") or [],
+        "expectedAnswer": row.get("flag_preview", ""),       # CyberArena{...}
+        "expectedAnswerHash": row.get("flag_hash", ""),      # server-side check
+        "explanation": "العلم يظهر في مخرجات الطرفية بعد تنفيذ الأمر الصحيح.",
+        "xpReward": row.get("xp_reward", 100),
+        "difficulty": row.get("difficulty", "متوسط"),
+        "files": files,
+        "fileMetadata": file_meta,
+        "commandOutputs": row.get("command_outputs") or {},
+        "toolsWhitelist": row.get("tools_whitelist") or [],
+        "challengeType": "crypto",
+    }
+
+
+def map_webex_row_to_training(row: dict, team_role: str) -> dict:
+    """Map a row from ``web_exploitation_challenges`` to TrainingData (v2)."""
+    files = row.get("files") or {}
+    file_meta = row.get("file_metadata") or {}
+    html_preview = row.get("html_preview") or ""
+    code_view = row.get("code_view") or ""
+    expected_payload = row.get("expected_payload") or ""
+    exploits_accepted = row.get("exploits_accepted") or []
+
+    primary_exploit = exploits_accepted[0] if exploits_accepted else expected_payload
+    expected_answer = f"{primary_exploit}|{row.get('flag_preview', '')}"
+
+    return {
+        "id": row.get("id"),
+        "scenarioId": row.get("id"),
+        "title": row.get("title", ""),
+        "story": row.get("story", ""),
+        # Challenge type is always 'web' for rows coming from
+        # web_exploitation_challenges — see the 011 normalization
+        # migration. The specific vuln family (xss, sqli, ...) lives
+        # in the ``topic`` column now.
+        "type": "web",
+        "topic": row.get("topic") or row.get("module", "xss"),
+        "vulnType": row.get("vuln_type", ""),
+        "task": row.get("task_outline", ""),
+
+        # v2 lab content
+        "code": html_preview,
+        "codeLanguage": "html",
+        "htmlPreview": html_preview,
+        "codeView": code_view,
+        "logData": None,
+        "configData": None,
+        "vulnerabilityLocation": f"نوع الثغرة: {row.get('vuln_type', '')} — ابحث عن الـ sink الخطير في الـ HTML",
+
+        # v2 validation metadata
+        "sinkType": row.get("sink_type", ""),
+        "validationPattern": row.get("validation_pattern", ""),
+        "exploitsAccepted": exploits_accepted,
+        # NOTE: secret_marker is NEVER sent to the client (security)
+        # Backend uses it during /api/training/evaluate-web
+
+        "hints": row.get("hints") or [],
+        "expectedAnswer": expected_answer,
+        "expectedAnswerHash": row.get("flag_hash", ""),
+        "expectedPayload": expected_payload,
+        "explanation": (
+            "الحل الصحيح: حقن payload يستغل الـ sink الموضّح في الكود المصدري. "
+            "أي vector مقبول من نفس عائلة الثغرة (مثلاً: "
+            f"{', '.join(exploits_accepted[:3]) if exploits_accepted else 'XSS vector'}"
+            ")."
+        ),
+        "xpReward": row.get("xp_reward", 100),
+        "difficulty": row.get("difficulty", "متوسط"),
+        "files": files,
+        "fileMetadata": file_meta,
+        "commandOutputs": row.get("command_outputs") or {},
+        "toolsWhitelist": row.get("tools_whitelist") or [],
+        "challengeType": "web",
+        "labKind": row.get("lab_kind", "iframe"),
+    }
+
+
+def map_code_fixing_row_to_training(row: dict, team_role: str) -> dict:
+    """Map a row from ``code_fixing_challenges`` to TrainingData."""
+    return {
+        "id": row.get("id"),
+        "scenarioId": row.get("id"),
+        "title": row.get("title", ""),
+        "story": row.get("story", ""),
+        "type": "code-fixing",
+        "topic": row.get("topic") or row.get("module", "code-fixing"),
+        "task": row.get("task_outline", ""),
+
+        # Additional fields for code-fixing
+        "language": row.get("language", "PYTHON"),
+        "vulnerable_code": row.get("vulnerable_code", ""),
+        "vulnerability_type": row.get("vulnerability_type", ""),
+        "vulnerability_description": row.get("vulnerability_description", ""),
+        "difficulty": row.get("difficulty", "متوسط"),
+        "xpReward": row.get("xp_reward", 150),
+        "hints": row.get("hints") or [],
+    }
+
+
+def map_log_analysis_row_to_training(row: dict, team_role: str) -> dict:
+    """Map a row from ``log_analysis_challenges`` to TrainingData."""
+    from app.core.config import SUPABASE_URL
+    storage_path = row.get("storage_path", "")
+    is_inline = storage_path.startswith("inline://")
+    actual_path = storage_path.replace("inline://", "") if is_inline else storage_path
+
+    log_url = ""
+    if not is_inline and SUPABASE_URL and actual_path:
+        log_url = f"{SUPABASE_URL}/storage/v1/object/public/log-analysis-files/{actual_path}"
+
+    return {
+        "id": row.get("id"),
+        "scenarioId": row.get("id"),
+        "title": row.get("title", ""),
+        "story": row.get("story", ""),
+        "type": "log-analysis",
+        "topic": row.get("topic") or row.get("module", "log-analysis"),
+        "task": row.get("task_outline", ""),
+        # Log-analysis specific
+        "log_type": row.get("log_type", "auth"),
+        "storage_path": storage_path,
+        "log_url": log_url,
+        "is_inline": is_inline,
+        "file_size_bytes": row.get("file_size_bytes", 0),
+        "vulnerability_description": row.get("vulnerability_description", ""),
+        "difficulty": row.get("difficulty", "متوسط"),
+        "xpReward": row.get("xp_reward", 150),
+        "hints": row.get("hints") or [],
+    }
+
+
+def map_vuln_hunter_row_to_training(row: dict, team_role: str) -> dict:
+    """Map a row from ``vulnerability_hunter_challenges`` to TrainingData.
+
+    Consumed by the Cyberpunk-themed VulnerabilityHunterEditor.
+    """
+    return {
+        "id": row.get("id"),
+        "scenarioId": row.get("id"),
+        "title": row.get("title", ""),
+        "story": row.get("story", ""),
+        "type": "vulnerability-hunter",
+        "topic": row.get("topic") or row.get("module", "vulnerability-hunter"),
+        "task": row.get("task_outline", ""),
+        "language": row.get("language", "PYTHON"),
+        "vulnerable_code": row.get("vulnerable_code", ""),
+        "vulnerability_type": row.get("vulnerability_type", ""),
+        "vulnerability_class": row.get("vulnerability_class", ""),
+        "vulnerability_description": row.get("vulnerability_description", ""),
+        "difficulty": row.get("difficulty", "متوسط"),
+        "xpReward": row.get("xp_reward", 150),
+        "hints": row.get("hints") or [],
+    }

app/services/completion_service.py

@@ -0,0 +1,64 @@
+"""Per-category completion tracker — powers certificate eligibility.
+
+Idempotent via ``UNIQUE(user_id, category, challenge_id)`` so duplicate
+``/api/training/solved`` calls never double-count.
+"""
+
+from typing import Optional
+
+import httpx
+
+from app.core.config import SUPABASE_URL, SUPABASE_ANON_KEY
+from app.services.supabase_service import supabase_headers
+
+
+async def record_user_completion(
+    user_id: Optional[str],
+    team_role: str,
+    category: str,
+    module: str,
+    challenge_id: str,
+    xp_awarded: int,
+):
+    """Insert (or ignore) a row in ``user_completions``."""
+    if not user_id:
+        return
+    if not (SUPABASE_URL and SUPABASE_ANON_KEY):
+        return
+    headers = supabase_headers(content_type=True)
+    headers["Prefer"] = "return=minimal,resolution=ignore-duplicates"
+    payload = {
+        "user_id": user_id,
+        "category": category,
+        "module": module,
+        "challenge_id": challenge_id,
+        "xp_awarded": int(xp_awarded or 0),
+    }
+    try:
+        async with httpx.AsyncClient(timeout=10) as client:
+            r = await client.post(
+                f"{SUPABASE_URL}/rest/v1/user_completions",
+                json=payload,
+                headers=headers,
+            )
+            if r.status_code not in (200, 201):
+                print(f"[completions] insert failed {r.status_code}: {r.text[:200]}")
+    except Exception as e:
+        print(f"[completions] insert exception: {e}")
+
+
+async def count_completions(user_id: str, category: str) -> int:
+    if not (SUPABASE_URL and SUPABASE_ANON_KEY):
+        return 0
+    url = (
+        f"{SUPABASE_URL}/rest/v1/user_completions"
+        f"?user_id=eq.{user_id}&category=eq.{category}&select=id"
+    )
+    try:
+        async with httpx.AsyncClient(timeout=10) as client:
+            r = await client.get(url, headers=supabase_headers())
+            if r.status_code == 200:
+                return len(r.json())
+    except Exception as e:
+        print(f"[completions] count exception: {e}")
+    return 0

app/services/evaluator.py

@@ -0,0 +1,715 @@
+"""AI-powered challenge evaluators (legacy + per-type).
+
+Each ``evaluate_*`` function consumes the request + scenario row, runs
+the appropriate AI (or pattern check), and returns the JSON shape the
+frontend expects. Where the result can be computed without AI (e.g. a
+plain flag check), we do so directly.
+"""
+
+import re
+from typing import Optional
+
+import httpx
+from fastapi import BackgroundTasks, HTTPException
+
+from app.core.constants import CYBER_SECURITY_TOPICS
+from app.core.security import (
+    normalize_str,
+    normalize_vuln_key,
+    ip_matches,
+    ioc_matches,
+    timestamp_close,
+)
+from app.core.config import GROQ_API_URL, GROQ_API_KEY, MISTRAL_API_URL, MISTRAL_MODEL, MISTRAL_API_KEY
+from app.core.text import parse_json_safe
+from app.services.supabase_service import fetch_scenario_by_id
+from app.services.scenario_service import handle_background_replacement
+from app.services.completion_service import record_user_completion
+
+
+# --------------------------------------------------------------------------- #
+#  Legacy: red-team / generic / blue-code-fix AI evaluator                    #
+# --------------------------------------------------------------------------- #
+
+async def evaluate_training(req, background_tasks: BackgroundTasks) -> dict:
+    """The original /api/training/evaluate (red-team payload + blue fix)."""
+    challenge = req.originalChallenge
+    user_code = req.userCode
+
+    eval_prompt = f"""أنت مهندس أمن سيبراني خبير ومراجع أكواد.
+مهمتك: تقييم الكود أو الاستغلال الذي قدمه المستخدم.
+دور المستخدم هو: {req.teamRole}
+
+إذا كان دور المستخدم هو "blue" (مدافع):
+- إذا كان الكود المعدل يسد الثغرة الأمنية ويحل المشكلة بشكل صحيح، أرجع secured: true.
+- إذا لم تحل المشكلة أو كان خاطئاً، أرجع secured: false.
+
+إذا كان دور المستخدم هو "red" (مهاجم):
+- إذا كان الكود (أو Payload) يستغل الثغرة بنجاح، أرجع secured: true (نقصد بها النجاح).
+- إذا كان الاستغلال فاشلاً، أرجع secured: false.
+
+أرجع JSON فقط:
+{{
+  "secured": true/false,
+  "feedback": "تقييمك باللغة العربية"
+}}
+
+التحدي الأصلي:
+- الثغرة: {challenge.get("vulnerabilityLocation", "")}
+- الإجابة المتوقعة: {challenge.get("expectedAnswer", "")}
+- الشرح: {challenge.get("explanation", "")}
+
+كود/استغلال المستخدم:
+{user_code}"""
+
+    print(f"[DEBUG] GROQ_API_KEY exists: {bool(GROQ_API_KEY)}")
+    print(f"[DEBUG] GROQ_API_KEY length: {len(GROQ_API_KEY) if GROQ_API_KEY else 0}")
+
+    async with httpx.AsyncClient(timeout=60) as client:
+        resp = await client.post(
+            GROQ_API_URL,
+            json={
+                "model": "llama-3.3-70b-versatile",
+                "messages": [
+                    {"role": "system", "content": "أنت مقيّم أكواد أمني. أعد JSON فقط."},
+                    {"role": "user", "content": eval_prompt},
+                ],
+                "temperature": 0.2,
+                "max_tokens": 1024,
+            },
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {GROQ_API_KEY}",
+            },
+        )
+
+    print(f"[DEBUG] Groq API response status: {resp.status_code}")
+    if resp.status_code != 200:
+        error_detail = f"Groq API error: {resp.status_code}"
+        try:
+            error_body = resp.text
+            print(f"[DEBUG] Groq API error body: {error_body}")
+            error_detail += f" - {error_body}"
+        except Exception:
+            pass
+        raise HTTPException(status_code=500, detail=error_detail)
+
+    content = resp.json()["choices"][0]["message"]["content"]
+    evaluation = parse_json_safe(content)
+
+    if evaluation.get("secured") is True:
+        scenario_id = challenge.get("scenarioId") or challenge.get("id")
+        if scenario_id:
+            module_name = challenge.get("type", "")
+            topic_info = CYBER_SECURITY_TOPICS.get(
+                module_name, {"path": "web-security", "category": "web"}
+            )
+            path = topic_info.get("path", "web-security")
+            category = topic_info.get("category", "web")
+            difficulty = challenge.get("difficulty", "متوسط")
+
+            background_tasks.add_task(
+                handle_background_replacement,
+                scenario_id,
+                req.teamRole,
+                module_name,
+                path,
+                category,
+                difficulty,
+            )
+
+    return {"evaluation": evaluation}
+
+
+# --------------------------------------------------------------------------- #
+#  Web exploitation — 3-layer validation (v2)                                 #
+# --------------------------------------------------------------------------- #
+
+async def evaluate_web_exploitation(req) -> dict:
+    """Layer 1 (PATTERN) + Layer 2 (SINK) + Layer 3 (SECRET)."""
+    challenge_id = req.challengeId
+    payload = (req.payload or "").strip()
+    signal = req.exploitSignal or {}
+
+    if not challenge_id:
+        return {"success": False, "error": "challengeId مفقود"}
+    if not payload:
+        return {"success": False, "error": "لم تُرسل payload", "layer": "input"}
+
+    row = await fetch_scenario_by_id(req.teamRole or "red", challenge_id, challenge_type="web")
+    if not row:
+        return {"success": False, "error": "التحدي غير موجود", "layer": "load"}
+
+    sink_expected = row.get("sink_type") or ""
+    secret_expected = row.get("secret_marker") or ""
+    pattern_str = row.get("validation_pattern") or ""
+    flag_preview = row.get("flag_preview") or ""
+    xp_reward = int(row.get("xp_reward") or 100)
+
+    user_flag = payload.strip().lower()
+    expected_flag = flag_preview.strip().lower()
+    expected_secret = secret_expected.strip().lower()
+
+    if user_flag == expected_flag or user_flag == expected_secret or user_flag.replace("cyberarena{", "").replace("}", "") == expected_secret:
+        print(f"[evaluate-web] flag solved directly: challenge={challenge_id}")
+        return {
+            "success": True,
+            "flag": flag_preview,
+            "xp": xp_reward,
+            "message": "تم استغلال الثغرة واستخراج العلم بنجاح! 🎉",
+            "layer": "all",
+            "sink_confirmed": True,
+        }
+
+    # ---- Layer 1: PATTERN ----
+    if pattern_str:
+        try:
+            if not re.search(pattern_str, payload, re.IGNORECASE):
+                return {
+                    "success": False,
+                    "error": "الـ payload لا يطابق نمط الثغرة المتوقع",
+                    "layer": "pattern",
+                    "hint": "راجع الكود المصدري وحدد نوع الـ sink (innerHTML / eval / SQL concat / SSRF / etc.)",
+                }
+        except re.error as e:
+            print(f"[evaluate-web] bad pattern in DB: {e}")
+            # Don't block the user on a backend regex bug
+
+    # ---- Layer 2: SINK ----
+    sink_observed = signal.get("sink") or ""
+    if sink_expected:
+        if not sink_observed:
+            return {
+                "success": False,
+                "error": "لم يثبت الـ sink تنفيذه في الـ iframe. حمّل الـ payload في المعاينة أولاً",
+                "layer": "sink",
+                "expected_sink": sink_expected,
+            }
+        if sink_observed != sink_expected:
+            return {
+                "success": False,
+                "error": f"الـ sink المُلتقَط ({sink_observed}) لا يطابق المتوقع ({sink_expected})",
+                "layer": "sink",
+                "expected_sink": sink_expected,
+                "observed_sink": sink_observed,
+            }
+
+    # ---- Layer 3: SECRET ----
+    secret_observed = signal.get("secret") or ""
+    if secret_expected:
+        if not secret_observed:
+            return {
+                "success": False,
+                "error": "لم نستلم الـ secret. الـ flag مخفي في الـ lab — استخدم الثغرة لاستخراجه (مثلاً عبر document.cookie أو الـ response)",
+                "layer": "secret",
+            }
+        if secret_observed.lower() != secret_expected.lower():
+            return {
+                "success": False,
+                "error": "الـ secret المُرسَل لا يطابق المتوقع",
+                "layer": "secret",
+            }
+
+    print(f"[evaluate-web] ✓ challenge={challenge_id} sink={sink_observed} secret_ok=True")
+    return {
+        "success": True,
+        "flag": flag_preview,
+        "xp": xp_reward,
+        "message": "تم استغلال الثغرة بنجاح! 🎉",
+        "layer": "all",
+        "sink_confirmed": sink_observed,
+    }
+
+
+# --------------------------------------------------------------------------- #
+#  Code-fix AI evaluator (single source of truth, shared with 1v1)            #
+# --------------------------------------------------------------------------- #
+
+async def ai_evaluate_code_fix(challenge_id: str, fixed_code: str, team_role: str = "blue") -> dict:
+    """Single source of truth for both /evaluate-code-fix and 1v1's blue verifier."""
+    row = await fetch_scenario_by_id(team_role or "blue", challenge_id, challenge_type="code-fixing")
+    if not row:
+        return {"secured": False, "feedback": "التحدي غير موجود"}
+
+    vulnerable_code = row.get("vulnerable_code") or ""
+    vuln_type = row.get("vulnerability_type") or ""
+    vuln_desc = row.get("vulnerability_description") or ""
+    language = row.get("language") or ""
+
+    eval_prompt = f"""أنت مهندس أمن سيبراني خبير ومراجع أكواد.
+
+مهمتك: تقييم الكود ال��ُعدل الذي قدمه المتدرب لتصحيح ثغرة أمنية.
+
+معلومات التحدي:
+- اللغة: {language}
+- نوع الثغرة: {vuln_type}
+- وصف الثغرة: {vuln_desc}
+
+الكود الأصلي (المصاب بالثغرة):
+```{language}
+{vulnerable_code}
+```
+
+الكود المُعدل من المتدرب:
+```{language}
+{fixed_code}
+```
+
+قيّم الكود المُعدل وتحقق من:
+1. هل الثغرة أُصلحت فعلياً؟
+2. هل الكود صحيح نحويًا (syntax)؟
+3. هل الحل يتبع أفضل الممارسات الأمنية؟
+
+قاعدة صارمة: اكتب حقل "feedback" باللغة العربية فقط. ممنوع منعاً باتاً استخدام أي كلمة بلغة أخرى.
+
+أرجع JSON صالحاً فقط بالشكل التالي (بدون أي نص قبله أو بعده):
+{{
+  "secured": true/false,
+  "feedback": "تقييمك المختصر بالعربية فقط يشرح هل الثغرة أُصلحت ولماذا",
+  "vulnerability_fixed": true/false,
+  "code_valid": true/false
+}}"""
+
+    print(f"[ai-evaluate-code-fix] challenge={challenge_id} lang={language}")
+
+    try:
+        async with httpx.AsyncClient(timeout=60) as client:
+            resp = await client.post(
+                GROQ_API_URL,
+                json={
+                    "model": "llama-3.3-70b-versatile",
+                    "messages": [
+                        {"role": "system", "content": "أنت مقيّم أكواد أمني. أعد JSON فقط."},
+                        {"role": "user", "content": eval_prompt},
+                    ],
+                    "temperature": 0.2,
+                    "max_tokens": 1024,
+                },
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {GROQ_API_KEY}",
+                },
+            )
+    except Exception as e:
+        return {"secured": False, "feedback": f"AI request failed: {e}"}
+
+    if resp.status_code != 200:
+        return {"secured": False, "feedback": f"AI evaluation error: {resp.status_code}"}
+
+    try:
+        content = resp.json()["choices"][0]["message"]["content"]
+        evaluation = parse_json_safe(content)
+    except Exception as e:
+        return {"secured": False, "feedback": f"AI response parse failed: {e}"}
+
+    if not isinstance(evaluation, dict):
+        return {"secured": False, "feedback": "AI response was not a JSON object"}
+    return evaluation
+
+
+async def evaluate_code_fix(req, background_tasks: BackgroundTasks) -> dict:
+    """Public /evaluate-code-fix handler (regular training)."""
+    challenge_id = req.challengeId
+    fixed_code = req.fixedCode
+
+    if not challenge_id:
+        return {"success": False, "error": "challengeId مفقود"}
+    if not fixed_code or not fixed_code.strip():
+        return {"success": False, "error": "لم تُرسل كود مُعدل"}
+
+    evaluation = await ai_evaluate_code_fix(challenge_id, fixed_code, req.teamRole or "blue")
+
+    if "error" in evaluation and "secured" not in evaluation:
+        return {"success": False, "error": evaluation.get("error", "AI evaluation failed")}
+
+    if evaluation.get("secured") is True:
+        row = await fetch_scenario_by_id(req.teamRole or "blue", challenge_id, challenge_type="code-fixing")
+        if row:
+            background_tasks.add_task(
+                handle_background_replacement,
+                challenge_id,
+                req.teamRole or "blue",
+                row.get("module", ""),
+                "web-security",
+                row.get("difficulty", "متوسط"),
+                row.get("difficulty", "متوسط"),
+            )
+            background_tasks.add_task(
+                record_user_completion,
+                req.userId,
+                req.teamRole or "blue",
+                "code-fixing",
+                row.get("module", ""),
+                challenge_id,
+                int(row.get("xp_reward") or 150),
+            )
+
+    return {"evaluation": evaluation}
+
+
+# --------------------------------------------------------------------------- #
+#  Log analysis — exact 4-field match + AI feedback via Mistral               #
+# --------------------------------------------------------------------------- #
+
+async def evaluate_log_analysis(req, background_tasks: BackgroundTasks) -> dict:
+    challenge_id = req.challengeId
+    if not challenge_id:
+        return {"success": False, "error": "challengeId مفقود"}
+
+    row = await fetch_scenario_by_id(req.teamRole or "blue", challenge_id, challenge_type="log-analysis")
+    if not row:
+        return {"success": False, "error": "التحدي غير موجود"}
+
+    expected_attack = normalize_str(row.get("expected_attack_type", ""))
+    expected_ip = row.get("expected_attacker_ip") or ""
+    expected_ts = row.get("expected_timestamp") or ""
+    expected_ioc = row.get("expected_ioc") or ""
+
+    correct_fields = []
+    if normalize_str(req.attackType) == expected_attack:
+        correct_fields.append("نوع الهجوم")
+    if ip_matches(req.attackerIp, expected_ip):
+        correct_fields.append("عنوان IP المهاجم")
+    if timestamp_close(req.timestamp, expected_ts):
+        correct_fields.append("الطابع الزمني")
+    if ioc_matches(req.ioc, expected_ioc):
+        correct_fields.append("مؤشر الاختراق (IOC)")
+
+    total = 4
+    score = int(len(correct_fields) * 100 / total)
+    passed = score >= 75  # need 3 of 4
+
+    # AI feedback (Arabic-only) via Mistral
+    feedback_text = await _log_analysis_ai_feedback(
+        row, expected_attack, expected_ip, expected_ts, expected_ioc,
+        req, correct_fields, total, passed,
+    )
+
+    if not feedback_text:
+        if passed:
+            feedback_text = f"تحليل ممتاز! حددت {len(correct_fields)} من {total} حقول بشكل صحيح. {row.get('vulnerability_description', '')}"
+        else:
+            missed = [f for f in ["نوع الهجوم", "عنوان IP المهاجم", "الطابع الزمني", "مؤشر الاختراق (IOC)"] if f not in correct_fields]
+            feedback_text = f"تم تحديد {len(correct_fields)} من {total} حقول. الحقول التي تحتاج مراجعة: {', '.join(missed)}. راجع السجل مرة أخرى وابحث عن الأنماط المشبوهة."
+
+    xp_awarded = int((row.get("xp_reward") or 150) * score / 100)
+
+    if passed:
+        background_tasks.add_task(
+            handle_background_replacement,
+            challenge_id,
+            req.teamRole or "blue",
+            row.get("module", "forensics"),
+            "forensics",
+            row.get("difficulty", "متوسط"),
+            row.get("difficulty", "متوسط"),
+        )
+        background_tasks.add_task(
+            record_user_completion,
+            req.userId,
+            req.teamRole or "blue",
+            "log-analysis",
+            row.get("module", "forensics"),
+            challenge_id,
+            xp_awarded,
+        )
+
+    return {
+        "evaluation": {
+            "passed": passed,
+            "score": score,
+            "correct_fields": correct_fields,
+            "feedback": feedback_text,
+            "xp_awarded": xp_awarded,
+        }
+    }
+
+
+async def _log_analysis_ai_feedback(
+    row, expected_attack, expected_ip, expected_ts, expected_ioc,
+    req, correct_fields, total, passed,
+) -> str:
+    """Use Mistral to generate a short Arabic SOC-style feedback paragraph."""
+    correct_str = "، ".join(correct_fields) if correct_fields else "لا شيء"
+    missed = [f for f in ["نوع الهجوم", "عنوان IP المهاجم", "الطابع الزمني", "مؤشر الاختراق (IOC)"] if f not in correct_fields]
+    missed_str = "، ".join(missed) if missed else "لا شيء"
+
+    feedback_prompt = f"""أنت محلل خبير في مركز عمليات الأمن السيبراني (SOC). راجع إجابة المتدرب.
+
+═══════════════════════════════════════
+قواعد اللغة (مطلوبة بصرامة):
+- اكتب بالعربية الفصحى فقط، بدون أي كلمات إنجليزية.
+- ممنوع منعاً باتاً استخدام: nor، and، or، the، to، of، in، على الإطلاق.
+- استخدم: و، أو، ثم، لكن، بل، لأن.
+- لا تذكر أسماء حقول تقنية (attack_type، IP، timestamp) — استخدم الأسماء العربية فقط.
+═══════════════════════════════════════
+
+معلومات التحدي:
+- العنوان: {row.get("title", "")}
+- نوع السجل: {row.get("log_type", "")}
+- نوع الهجوم الصحيح: {expected_attack}
+- عنوان الـ IP الصحيح: {expected_ip}
+- الطابع الزمني الصحيح: {expected_ts}
+- مؤشر الاختراق الصحيح: {expected_ioc}
+
+إجابة المتدرب:
+- نوع الهجوم: {req.attackType or "(فارغ)"}
+- عنوان الـ IP: {req.attackerIp or "(فارغ)"}
+- الطابع الزمني: {req.timestamp or "(فارغ)"}
+- مؤشر الاختراق: {req.ioc or "(فارغ)"}
+- التحليل الحر: {req.explanation or "(لم يكتب شيئاً)"}
+
+نتيجة التقييم: {len(correct_fields)} من {total} حقول صحيحة.
+الحقول الصحيحة: {correct_str}
+الحقول الخاطئة أو الفارغة: {missed_str}
+
+═══════════════════════════════════════
+التعليمات:
+- اكتب فقرة واحدة إلى ثلاث فقرات قصيرة بالعربية فقط.
+- ابدأ بجملة افتتاحية تصف النتيجة (مثلاً: "أصبت في X من Y" أو "لم تتمكن من كشف أي حقل بشكل صحيح").
+- إذا كانت النتيجة 3 أو 4 من 4: امدح المتدرب وأض�� سياقاً أمنياً مختصراً.
+- إذا كانت النتيجة أقل من 3: وضّح الحقول التي أخطأ فيها وقل كيف يكتشفها مستقبلاً، مع ربط بالإجابة الصحيحة.
+- لا تتجاوز 150 كلمة.
+═══════════════════════════════════════
+
+أرجع JSON فقط بدون أي شرح إضافي:
+{{"feedback": "النص هنا"}}"""
+
+    try:
+        async with httpx.AsyncClient(timeout=60) as client:
+            fb_resp = await client.post(
+                MISTRAL_API_URL,
+                json={
+                    "model": MISTRAL_MODEL,
+                    "messages": [
+                        {"role": "system", "content": "أنت محلل خبير في مركز عمليات الأمن السيبراني (SOC). أرجع JSON فقط، اكتب بالعربية الفصحى حصراً، ولا تستخدم أي كلمات إنجليزية على الإطلاق."},
+                        {"role": "user", "content": feedback_prompt},
+                    ],
+                    "temperature": 0.3,
+                    "max_tokens": 1024,
+                    "response_format": {"type": "json_object"},
+                },
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {MISTRAL_API_KEY}",
+                },
+            )
+        if fb_resp.status_code == 200:
+            fb_content = fb_resp.json()["choices"][0]["message"]["content"]
+            fb_data = parse_json_safe(fb_content)
+            return fb_data.get("feedback", "")
+        print(f"[log-analysis eval] Mistral HTTP {fb_resp.status_code}: {fb_resp.text[:200]}")
+    except Exception as e:
+        print(f"[log-analysis eval] AI feedback failed: {e}")
+    return ""
+
+
+# --------------------------------------------------------------------------- #
+#  Vulnerability hunter — exact canonical-key match                           #
+# --------------------------------------------------------------------------- #
+
+# Common alias → canonical form. Pre-filters well-known abbreviations so
+# we don't pay for a Mistral call when the user types "sqli" or "xss".
+# If the alias matches, the answer is treated as exact-match (full XP).
+_VULN_ALIASES: dict[str, str] = {
+    "sqli": "sql-injection",
+    "sql": "sql-injection",
+    "sqlinj": "sql-injection",
+    "xss": "xss",
+    "crosssitescripting": "xss",
+    "csrf": "csrf",
+    "xsrf": "csrf",
+    "ssrf": "ssrf",
+    "xxe": "xxe",
+    "idor": "idor",
+    "lfi": "local-file-inclusion",
+    "rfi": "remote-file-inclusion",
+    "rce": "remote-code-execution",
+    "lpe": "local-privilege-escalation",
+    "privesc": "privilege-escalation",
+    "bof": "buffer-overflow",
+    "uaf": "use-after-free",
+    "formatstring": "format-string",
+    "integeroverflow": "integer-overflow",
+    "npd": "null-pointer-dereference",
+    "doublefree": "double-free",
+    "offbyone": "off-by-one",
+    "uninit": "uninitialized-memory",
+    "race": "race-condition",
+    "toctou": "time-of-check-time-of-use",
+    "proto": "prototype-pollution",
+    "deserialization": "insecure-deserialization",
+    "misconfig": "security-misconfiguration",
+    "bac": "broken-access-control",
+    "openredirect": "open-redirect",
+    "ssti": "server-side-template-injection",
+}
+
+
+def _alias_resolve(s: str) -> str:
+    """Lowercase + strip dashes/spaces. Returns the normalised token or the
+    canonical alias if it matches ``_VULN_ALIASES``."""
+    if not s:
+        return ""
+    norm = re.sub(r"[\s_\-]+", "", (s or "").lower().strip())
+    return _VULN_ALIASES.get(norm, norm)
+
+
+async def _grade_vuln_hunter_with_mistral(
+    user_answer: str,
+    expected: str,
+) -> dict:
+    """Ask Mistral to grade the student's vuln-name answer semantically.
+
+    Returns ``{similarity, is_match, reason, xp_ratio}``. ``xp_ratio`` is
+    clamped between 0.4 and 1.0 when ``is_match`` is true (so partial
+    credit is always at least 40% of the reward). Returns
+    ``{"similarity": 0.0, "is_match": False, "reason": "...", "xp_ratio": 0}``
+    on any Mistral error so the caller can fall back to a hard fail.
+    """
+    if not MISTRAL_API_KEY:
+        return {"similarity": 0.0, "is_match": False, "reason": "Mistral not configured", "xp_ratio": 0}
+
+    system_prompt = (
+        "You are a senior cybersecurity instructor grading a student's answer "
+        "in an Arabic-first training platform. The student is asked to name a "
+        "specific vulnerability class shown in a code exhibit. Compare the "
+        "STUDENT_ANSWER to the EXPECTED_ANSWER and decide if they refer to the "
+        "same vulnerability.\n\n"
+        "Aliases are equivalent (e.g. 'sqli' = 'sql-injection', "
+        "'xss' = 'cross-site-scripting', 'bof' = 'buffer-overflow', "
+        "'rce' = 'remote-code-execution'). Different specific attack families "
+        "are NOT the same (e.g. 'sql-injection' is NOT 'xss').\n\n"
+        "Return raw JSON only, no markdown:\n"
+        '{"similarity": 0.0-1.0, "is_match": true|false, "reason": "..."}'
+    )
+    user_prompt = (
+        f"EXPECTED_ANSWER: {expected}\n"
+        f"STUDENT_ANSWER: {user_answer}\n\n"
+        "Are these the same vulnerability? Grade it."
+    )
+
+    try:
+        async with httpx.AsyncClient(timeout=20) as client:
+            r = await client.post(
+                MISTRAL_API_URL,
+                json={
+                    "model": MISTRAL_MODEL,
+                    "messages": [
+                        {"role": "system", "content": system_prompt},
+                        {"role": "user", "content": user_prompt},
+                    ],
+                    "temperature": 0.0,
+                    "max_tokens": 300,
+                    "response_format": {"type": "json_object"},
+                },
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {MISTRAL_API_KEY}",
+                },
+            )
+        if r.status_code != 200:
+            return {"similarity": 0.0, "is_match": False, "reason": f"Mistral HTTP {r.status_code}", "xp_ratio": 0}
+        content = r.json().get("choices", [{}])[0].get("message", {}).get("content", "")
+        data = parse_json_safe(content) or {}
+        similarity = float(data.get("similarity", 0) or 0)
+        is_match = bool(data.get("is_match", False)) or similarity >= 0.65
+        reason = str(data.get("reason", "")).strip() or "تم التقييم بواسطة Mistral"
+        xp_ratio = 0
+        if is_match:
+            xp_ratio = max(0.4, min(1.0, similarity)) if similarity >= 0.95 else max(0.4, min(0.85, similarity * 0.9))
+        return {"similarity": round(similarity, 3), "is_match": is_match, "reason": reason, "xp_ratio": xp_ratio}
+    except Exception as e:
+        return {"similarity": 0.0, "is_match": False, "reason": f"Mistral error: {e}", "xp_ratio": 0}
+
+
+async def evaluate_vuln_hunter(req, background_tasks: BackgroundTasks) -> dict:
+    challenge_id = req.challengeId
+    if not challenge_id:
+        return {"success": False, "error": "challengeId مفقود"}
+    if not (req.vulnerabilityType or "").strip():
+        return {"success": False, "error": "لم تُرسل اسم الثغرة"}
+
+    row = await fetch_scenario_by_id(req.teamRole or "blue", challenge_id, challenge_type="vulnerability-hunter")
+    if not row:
+        return {"success": False, "error": "التحدي غير موجود"}
+
+    expected = normalize_vuln_key(row.get("vulnerability_type", ""))
+    user = normalize_vuln_key(req.vulnerabilityType)
+    # Also resolve common aliases ("sqli" → "sql-injection", "xss" → "xss").
+    # This catches well-known abbreviations without paying for a Mistral call.
+    user_resolved = _alias_resolve(req.vulnerabilityType)
+    expected_resolved = _alias_resolve(row.get("vulnerability_type", ""))
+    correct = (bool(expected) and (user == expected)) or (
+        bool(expected_resolved) and (user_resolved == expected_resolved)
+    )
+
+    xp_reward = int(row.get("xp_reward") or 150)
+    ai_grade: dict = {"similarity": 0.0, "is_match": False, "reason": "", "xp_ratio": 0}
+    if not correct:
+        # Ask Mistral to compare semantically when the alias/exact match fails.
+        # This recognises near-misses and ambiguous phrasing so the student
+        # gets partial credit instead of a hard fail.
+        ai_grade = await _grade_vuln_hunter_with_mistral(
+            req.vulnerabilityType, row.get("vulnerability_type", "")
+        )
+
+    passed = correct or ai_grade["is_match"]
+    if ai_grade["is_match"]:
+        xp_awarded = int(xp_reward * ai_grade["xp_ratio"])
+    elif correct:
+        xp_awarded = xp_reward
+    else:
+        xp_awarded = 0
+
+    if passed:
+        background_tasks.add_task(
+            handle_background_replacement,
+            challenge_id,
+            req.teamRole or "blue",
+            row.get("module", "vulnerability-hunter"),
+            "web-security",
+            row.get("difficulty", "متوسط"),
+            row.get("difficulty", "متوسط"),
+        )
+        background_tasks.add_task(
+            record_user_completion,
+            req.userId,
+            req.teamRole or "blue",
+            "vulnerability-hunter",
+            row.get("module", "vulnerability-hunter"),
+            challenge_id,
+            xp_awarded,
+        )
+
+    if correct:
+        feedback = (
+            "إجابة صحيحة! الثغرة هي فعلاً "
+            f"{expected}. {row.get('vulnerability_description', '')}"
+        ).strip()
+    elif ai_grade["is_match"]:
+        feedback = (
+            f"إجابة قريبة ({int(ai_grade['similarity'] * 100)}% تشابه). "
+            f"الثغرة المتوقعة: {row.get('vulnerability_type', 'غير معروف')}. "
+            f"تم احتساب {xp_awarded} من {xp_reward} XP. {ai_grade.get('reason', '')}"
+        ).strip()
+    else:
+        feedback = (
+            f"الثغرة المتوقعة هي: {row.get('vulnerability_type', 'غير معروف')}. "
+            f"{row.get('vulnerability_description', '')}"
+        ).strip()
+
+    return {
+        "success": True,
+        "evaluation": {
+            "passed": passed,
+            "score": int((100 if correct else (ai_grade["similarity"] * 100)) if passed else 0),
+            "feedback": feedback,
+            "xp_awarded": xp_awarded,
+            "similarity": ai_grade["similarity"],
+            "ai_graded": ai_grade["is_match"] and not correct,
+            "ai_reason": ai_grade.get("reason", ""),
+            "vulnerability_type": row.get("vulnerability_type", ""),
+            "vulnerability_class": row.get("vulnerability_class", ""),
+        },
+    }

app/services/file_storage.py

@@ -0,0 +1,68 @@
+"""Upload AI-generated challenge files to Supabase Storage.
+
+The backend NEVER writes files to its own disk — every
+``fileToGenerate`` payload is uploaded to the public
+``challenge-files`` Supabase Storage bucket and the resulting URL is
+returned in the training payload (``logData.downloadable_url``) so
+the frontend can offer a direct download link.
+
+If the upload fails for any reason, the function still returns a
+best-effort relative path string and the rest of the challenge still
+loads — the file just becomes a no-op for that one challenge.
+"""
+
+import time
+
+import httpx
+
+from app.core.config import (
+    SUPABASE_URL,
+    SUPABASE_ANON_KEY,
+    CHALLENGE_FILES_BUCKET,
+)
+
+
+def _public_url(storage_path: str) -> str:
+    """Build the public URL for an object in the bucket."""
+    return f"{SUPABASE_URL}/storage/v1/object/public/{CHALLENGE_FILES_BUCKET}/{storage_path}"
+
+
+async def upload_challenge_file(file_data: dict, module: str, team_role: str) -> str:
+    """Upload the ``fileToGenerate`` payload to Supabase Storage.
+
+    Returns the **public URL** of the uploaded object, or ``""`` if
+    nothing was saved.
+    """
+    if not file_data or not file_data.get("fileName") or not file_data.get("content"):
+        return ""
+
+    file_name = str(file_data.get("fileName")).replace(" ", "_")
+    content = file_data.get("content")
+
+    # Sanitize the filename: strip path components + traversal sequences.
+    safe_name = file_name.replace("\\", "/").split("/")[-1].replace("..", "_")
+    if not safe_name:
+        return ""
+
+    # Object key: <team>/<module>/<timestamp>_<name> so two solves
+    # with the same filename never overwrite each other.
+    storage_path = f"{team_role}/{module}/{int(time.time())}_{safe_name}"
+
+    upload_url = f"{SUPABASE_URL}/storage/v1/object/{CHALLENGE_FILES_BUCKET}/{storage_path}"
+    headers = {
+        "apikey": SUPABASE_ANON_KEY,
+        "Authorization": f"Bearer {SUPABASE_ANON_KEY}",
+        "Content-Type": "application/octet-stream",
+    }
+
+    try:
+        async with httpx.AsyncClient(timeout=15) as client:
+            resp = await client.post(upload_url, content=content.encode("utf-8"), headers=headers)
+            if resp.status_code in (200, 201):
+                print(f"    [+] تم رفع ملف التحدي إلى Storage: {storage_path}")
+                return _public_url(storage_path)
+            print(f"    [-] فشل رفع الملف إلى Storage: {resp.status_code} {resp.text[:200]}")
+    except Exception as e:
+        print(f"    [-] استثناء أثناء رفع الملف إلى Storage: {e}")
+    return ""
+

app/services/scenario_service.py

@@ -0,0 +1,491 @@
+"""Scenario generation service.
+
+Three things live here:
+  * ``generate_scenario_from_groq`` — pulls a fresh *scenario seed*
+    (title + story + task) from Groq for the pool cache.
+  * ``generate_challenge_from_groq`` — turns a scenario seed into a
+    full interactive challenge (HTML, files, hints, expected answer).
+  * ``generate_and_store_scenario`` / ``handle_background_replacement``
+    — background-task glue used by the routers and the pool watcher.
+"""
+
+import os
+import random
+from typing import Optional
+
+import httpx
+from fastapi import HTTPException
+
+from app.core.constants import CYBER_SECURITY_TOPICS, FALLBACK_HTML
+from app.core.config import GROQ_API_URL, GROQ_API_KEY
+from app.core.text import parse_json_safe
+from app.services.supabase_service import (
+    SUPABASE_URL,
+    SUPABASE_ANON_KEY,
+    supabase_headers,
+    insert_scenario_to_supabase,
+    delete_scenario_from_supabase,
+    fetch_scenario_by_id,
+    scenario_table,
+)
+
+
+# --------------------------------------------------------------------------- #
+#  Scenario seed (cache pool)                                                 #
+# --------------------------------------------------------------------------- #
+
+async def generate_scenario_from_groq(
+    team_role: str,
+    module: str,
+    path: str = "web-security",
+    category: str = "web",
+    difficulty: str = "متوسط",
+) -> dict:
+    """Generate a lightweight scenario seed for the cache pool (no full challenge artifacts)."""
+    topic_info = CYBER_SECURITY_TOPICS.get(
+        module, {"name": f"موضوع: {module}", "category": category, "path": path}
+    )
+    topic = topic_info["name"]
+    team_label = "الفريق الأزرق (مدافع)" if team_role == "blue" else "الفريق الأحمر (مهاجم)"
+
+    # Pull recent titles to avoid duplicates
+    existing_titles = await _fetch_existing_titles(team_role)
+
+    system_prompt = f"""أنت كبير مصممي سيناريوهات الأمن السيبراني في منصة APEX، وتعمل بمعايير المنصات العالمية (HackTheBox، PortSwigger، SANS، MITRE ATT&CK، PicoCTF).
+
+مهمتك: تصميم سيناريو تدريبي **مبتكر وواقعي** بمستوى احترافي عالٍ.
+السيناريو سيُستخدم كقصة أساسية يبني عليها ذكاء اصطناعي آخر تحدٍ تفاعلي كامل.
+
+### الدور
+{team_label}
+
+### الموضوع التقني
+{topic} (module key: {module})
+
+### مستوى الصعوبة
+{difficulty}
+
+### قواعد الجودة الصارمة (مهم جداً)
+1. **واقعية قصوى**: السيناريو يجب أن يكون مستوحى من حادثة أمنية حقيقية أو حالة اختراق معروفة (مثل اختراق SolarWinds، ثغرة Log4Shell، تسريبات Capital One S3، تسريبات Facebook GraphQL، Kerberoasting، إلخ). لا قصص طفولية.
+2. **تفاصيل تقنية دقيقة**: اذكر تقنيات حقيقية (CVEs بأرقامها، نُسخ منتجات، أدوات)، أسماء شركات وهمية واقعية، أرقام دقيقة (IP، نطاقات، hashes، endpoints، CVSS scores).
+3. **تنوع**: لا تكرّر نفس القصة/السيناريو بتغييرات طفيفة. كل سيناريو يجب أن يحكي قصة فريدة.
+4. **بيئة تقنية محددة**: اذكر stack تقني واضح (مثل Nginx 1.18, MySQL 8, AWS EC2 t3.medium, K8s 1.28, Active Directory 2019، إلخ).
+5. **مخرجات قابلة للقياس**: الـ "task" يجب أن يحدد مهمة واحدة واضحة ومحددة يمكن للذكاء الاصطناعي التالي تحويلها إلى تحدٍ تفاعلي.
+6. **تخصص**: استخدم مصطلحات أمان سيبراني احترافية (TTPs من MITRE ATT&CK، CVE/CWE، IOC، C2، lateral movement، exfiltration، persistence).
+
+### منع التكرار
+العناوين الموجودة حالياً في البركة (لا تُكرّرها أو تشابهها):
+{', '.join(existing_titles[:25]) if existing_titles else 'لا يوجد'}
+
+### الإخراج (JSON خام فقط، بدون Markdown)
+{{
+  "title": "عنوان احترافي مبتكر بالإنجليزية أو العربية يصف السيناريو بدقة",
+  "story": "قصة سياقية واقعية (3-4 جمل) تصف: من الشركة؟ ما التقنية المستخدمة؟ ما الثغرة أو السياق الأمني؟ ما الأثر؟",
+  "task": "مهمة واحدة واضحة ومحددة باللغة العربية (فقرة واحدة) تصف ما يجب على المتدرب فعله",
+  "difficulty": "{difficulty}",
+  "xpReward": {200 if difficulty == "قوي" else 150 if difficulty == "متوسط" else 100}
+}}"""
+
+    # Pick a creative seed based on difficulty + module to ensure variety
+    creative_seeds = [
+        f"حادثة أمنية في شركة {random.choice(['CloudWave', 'FinShield', 'TechCorp', 'MediCore', 'DataHub', 'ApexBank', 'NexusLogistics', 'QuantumHealth', 'SolarSync', 'PayStream'])}",
+        f"سيناريو هجوم/دفاع مبني على {random.choice(['MITRE ATT&CK T1059', 'CVE-2024-3094', 'OWASP API Top 10', 'NIST SP 800-53', 'PCI-DSS violation', 'insider threat', 'supply chain attack', 'zero-day exploit', 'privilege escalation chain'])}",
+        f"بيئة {random.choice(['Kubernetes 1.28', 'AWS EKS', 'Azure AD', 'GCP IAM', 'Active Directory 2019', 'Java Spring Boot', 'Node.js Express', 'PHP 8.2', 'Python FastAPI', 'Go microservice', 'React SPA', 'GraphQL API'])} مع {random.choice(['misconfig', 'memory leak', 'race condition', 'TOCTOU', 'insecure deserialization', 'weak crypto'])}",
+    ]
+    user_prompt = (
+        f"صمم سيناريو {team_label} جديد وحصري عن {topic}.\n"
+        f"الإلهام: {random.choice(creative_seeds)}.\n"
+        f"تذكير: اجعل السيناريو **مختلفاً كلياً** عن العناوين السابقة، واذكر stack تقني محدد، واصف الأثر بالأرقام (مستخدمين/سجلات/دولار)."
+    )
+
+    async with httpx.AsyncClient(timeout=60) as client:
+        resp = await client.post(
+            GROQ_API_URL,
+            json={
+                "model": "llama-3.3-70b-versatile",
+                "messages": [
+                    {"role": "system", "content": "أنت مقيّم أكواد أمني خبير. أعد JSON صالحاً فقط بدون أي نص قبله أو بعده. اكتب جميع القيم النصية باللغة العربية حصراً. لا تستخدم أي لغة أخرى (لا إنجليزية، لا صينية، لا أي لغة غير العربية) في حقل feedback."},
+                    {"role": "user", "content": user_prompt},
+                ],
+                "temperature": 0.2,
+                "max_tokens": 2048,
+            },
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {GROQ_API_KEY}",
+            },
+        )
+
+    if resp.status_code == 429:
+        raise ValueError("Groq API Rate Limit Reached (429)")
+    if resp.status_code != 200:
+        raise HTTPException(status_code=500, detail=f"Groq API error: {resp.status_code}")
+
+    return parse_json_safe(resp.json()["choices"][0]["message"]["content"])
+
+
+async def _fetch_existing_titles(team_role: str) -> list:
+    """Fetch recent scenario titles for uniqueness check."""
+    if not SUPABASE_ANON_KEY or not SUPABASE_URL:
+        return []
+    table = scenario_table(team_role)
+    url = f"{SUPABASE_URL}/rest/v1/{table}?select=title&team_role=eq.{team_role}&order=created_at.desc&limit=40"
+    try:
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(url, headers=supabase_headers())
+            if resp.status_code == 200:
+                return [row.get("title", "") for row in resp.json() if row.get("title")]
+    except Exception:
+        pass
+    return []
+
+
+# --------------------------------------------------------------------------- #
+#  Full challenge (from scenario or from scratch)                             #
+# --------------------------------------------------------------------------- #
+
+async def generate_challenge_from_scenario(
+    scenario: dict,
+    team_role: str,
+    module: str,
+    path: str = "web-security",
+    category: str = "web",
+) -> dict:
+    """Build a full interactive challenge from a cached scenario via Groq."""
+    difficulty = scenario.get("difficulty") or "متوسط"
+    return await generate_challenge_from_groq(
+        team_role, module, path, category, difficulty, scenario=scenario
+    )
+
+
+async def generate_challenge_from_groq(
+    team_role: str,
+    module: str,
+    path: str = "web-security",
+    category: str = "web",
+    difficulty: str = "متوسط",
+    scenario: Optional[dict] = None,
+) -> dict:
+    """Build a complete interactive challenge via Groq."""
+    topic_info = CYBER_SECURITY_TOPICS.get(
+        module, {"name": f"موضوع: {module}", "category": category, "path": path}
+    )
+    topic = topic_info["name"]
+
+    is_web = module in ["xss", "sqli", "csrf", "ssrf", "idor", "lfi-rfi", "xxe", "cmdi", "auth", "upload"]
+
+    role_instructions = _build_role_instructions(module, team_role, difficulty, is_web)
+
+    if scenario:
+        scenario_block = f"""
+=== السيناريو الأساسي (يجب الالتزام به بالكامل) ===
+عنوان السيناريو: {scenario.get("title", "")}
+قصة السيناريو: {scenario.get("story", "")}
+ملخص المهمة: {scenario.get("task_outline") or scenario.get("task", "")}
+=== نهاية السيناريو ===
+
+يجب أن تبني التحدي الكامل (HTML، الملفات، التلميحات، الإجابة المتوقعة) انطلاقاً من هذا السيناريو.
+يمكنك توسيع التفاصيل التقنية، لكن لا تغيّر جوهر القصة أو الهدف الأمني.
+"""
+    else:
+        scenario_block = "لا يوجد سيناريو مسبق — أنشئ تحدياً أصلياً يتوافق مع الموضوع والدور."
+
+    system_prompt = f"""أنت مدرب أمن سيبراني خبير ومحترف للغاية.
+مهمتك: بناء تحدٍ تفاعلي كامل ومفصّل بناءً على السيناريو المُزوَّد أدناه.
+لا تنحرف عن السيناريو — طوّره إلى تحدٍ قابل للعب مع أكواد وملفات وتلميحات وإجابة متوقعة.
+درجة الصعوبة المطلوبة للتحدي: {difficulty}
+{role_instructions}
+{scenario_block}
+
+قواعد صارمة لواقعية التحدي (Realistic & Production-Ready Scenarios):
+1. يمنع منعاً باتاً كتابة سيناريوهات وهمية أو أكواد غير حقيقية أو استبدال الأكواد بتعليقات توضيحية. يجب أن يكون الكود المصدري كاملاً وقابلاً للتنفيذ ومطابقاً للواقع البرمجي 100%.
+2. يجب صياغة القصة والسيناريو والمهام بشكل واقعي ومأخوذ من حوادث أمنية حقيقية أو حالات اختراق معروفة في الشركات والأنظمة الحية، وتجنب القصص التبسيطية أو الطفولية.
+3. يجب أن تحتوي الـ htmlPreview على كود برمجي متكامل ومبني بعناية فائقة، ويحتوي على الخلل الأمني الدقيق (مثل استخدام غير آمن للدوال, عدم فلترة المدخلات، ثغرات التوجيه، التشفير الضعيف، إلخ).
+4. بالنسبة للبلو تيم: يجب أن يكون الحل قابلاً للتطبيق برمجياً (مثل استبدال الدوال الضعيفة ببدائل حقيقية وآمنة)، ويجب أن يحتوي التحدي على وصف برمني وتفسير دقيق للثغرة في حقل vulnerabilityLocation.
+5. بالنسبة للريد تيم: يجب أن تكون الثغرة قابلة للاستغلال الفعلي، والـ expectedAnswer يجب أن تحتوي على حمولات واقعية ومقبولة برمجياً.
+
+مهم جداً: أرجع JSON خام فقط بدون أي Markdown أو شرح أو أسطر إضافية أو ```json.
+
+أرجع JSON فقط وبشكل صحيح، بهذا التنسيق وبدون أي نصوص إضافية خارج الـ JSON:
+
+{{
+  "title": "عنوان التدريب المناسب للمسار والدور",
+  "story": "قصة سيبرانية واقعية وحماسية باللغة العربية مأخوذة من سيناريو شركة أو بيئة إنتاج حقيقية",
+  "task": "المهمة المطلوبة من المستخدم بوضوح تام وبلغة أمنية دقيقة",
+  "htmlPreview": "صفحة HTML كاملة تفاعلية وحقيقية تحتوي على كود وتصميم ذو جودة عالية جداً وخلفيات داكنة متناسقة مع هوية CyberArena السيبرانية",
+  "fileToGenerate": {{
+    "fileName": "اسم الملف مع الامتداد المناسب (مثل capture.log أو hashes.txt)",
+    "content": "المحتوى الفعلي للملف الذي سيقوم المتدرب بتحميله وتحليله"
+  }},
+  "vulnerabilityLocation": "تحديد وتفسير دقيق جداً لمكان وجود الثغرة برمجياً ومنطقياً في الكود",
+  "hints": ["تلميح تقني عميق يساعده في الحل","تلميح إضافي","تلميح يوضح الفكرة تماماً"],
+  "expectedAnswer": "الاستغلال المتوقع أو الحمولة (payload) المتوقعة بالنسبة للفريق الأحمر، أو فكرة الحل للفريق الأزرق",
+  "explanation": "شرح أمني عميق للثغرة وكيفية معالجتها في الواقع والأبعاد الأمنية لها وكيفية تجنبها في بيئات الإنتاج",
+  "configData": "محتوى ملف التهيئة أو الشيفرة البرمجية المفترضة للتحدي (مثال: محتويات ملف التشفير الضعيف، أو ملف secret.enc المشفر، أو إعدادات الشبكة) بشكل نصي كامل إذا كان التحدي يحتاج ملفات للتأمين أو الفك.",
+  "logData": "محتوى سجلات النظام أو حزم الشبكة النصية المفترضة بدقة وواقعية.",
+  "xpReward": {200 if difficulty == "قوي" else 150 if difficulty == "متوسط" else 100},
+  "difficulty": "{difficulty}"
+}}
+
+ملاحظة هامة: يجب أن تكون صفحة htmlPreview تفاعلية بالكامل، ذات ألوان داكنة تتطابق مع هوية CyberArena السيبرانية الفخمة، وتدعم اللغة العربية والاتجاه RTL.
+
+تنبيه للمبرمج: يمنع استخدام كلمات من مسارات أخرى في غير محلها (مثلاً ��ا تستخدم "تشفير" أو "جدار حماية" في تحدي XSS أو SQL Injection) حتى لا يتم استبعاد التحدي من نظام التدقيق آلياً."""
+
+    user_prompt = f"""الموضوع: {topic}
+الوحدة: {module}
+دور اللاعب الحالي: {team_role}
+درجة الصعوبة المطلوبة: {difficulty}
+المسار: {path}
+التصنيف: {category}
+
+بناءً على السيناريو المُزوَّد، أنشئ تحدياً تفاعلياً كاملاً جاهزاً للعب."""
+
+    async with httpx.AsyncClient(timeout=60) as client:
+        resp = await client.post(
+            GROQ_API_URL,
+            json={
+                "model": "llama-3.3-70b-versatile",
+                "messages": [
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_prompt},
+                ],
+                "temperature": 0.7,
+                "max_tokens": 4096,
+            },
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {GROQ_API_KEY}",
+            },
+        )
+
+    if resp.status_code == 429:
+        raise ValueError("Groq API Rate Limit Reached (429)")
+    elif resp.status_code != 200:
+        raise HTTPException(status_code=500, detail=f"Groq API error: {resp.status_code}")
+
+    content = resp.json()["choices"][0]["message"]["content"]
+    training = parse_json_safe(content)
+
+    if not training.get("htmlPreview", "").strip():
+        training["htmlPreview"] = FALLBACK_HTML
+
+    return training
+
+
+def _build_role_instructions(module: str, team_role: str, difficulty: str, is_web: bool) -> str:
+    """The role-specific guidance block injected into the Groq system prompt."""
+    if is_web:
+        if team_role == "blue":
+            return f"""
+المستخدم هو من الفريق الأزرق (Blue Team - مدافع أمني) في مسار الويب والتطبيقات.
+يجب أن تركز المهمة والقصة والخطوات بالكامل على الجانب الدفاعي وسد الثغرة البرمجية في صفحة الويب.
+درجة الصعوبة المطلوبة للتحدي: {difficulty}
+- يجب أن يكون التحدي عبارة عن كود مصاب بثغرة أمنية واضحة في ملف index.html.
+- المطلوب من المستخدم هو فتح محرر الأكواد (VS Code) وتعديل الكود المصدري لسد الثغرة الأمنية وجعل الصفحة آمنة تماماً.
+- اجعل قصة التحدي تدور حول مهندس أمن يقوم بإصلاح وتأمين نظام ويب تم اكتشاف ثغرة فيه.
+- اجعل "task" واضحة جداً وتطلب منه صراحة تعديل الكود المصدري لإغلاق الثغرة (مثلاً استبدال الكود غير الآمن ببديل آمن).
+- لا تطلب منه أبداً إدخال payload أو البحث عن علم (flag)، بل اطلب منه إصلاح الكود والضغط على 'أكملت الإصلاح' ليقوم المقيم الذكي بفحص الكود.
+"""
+        return f"""
+المستخدم هو من الفريق الأحمر (Red Team - مهاجم ومخترق) في مسار الويب والتطبيقات.
+يجب أن تركز المهمة والقصة والخطوات بالكامل على الجانب الهجومي واكتشاف الثغرة واستغلالها في الويب.
+درجة الصعوبة المطلوبة للتحدي: {difficulty}
+- المطلوب من المستخدم هو اكتشاف الثغرة في الموقع التفاعلي وحقن حمولة مناسبة (payload) أو إيجاد العلم (flag) للحصول على النقاط.
+- اجعل قصة التحدي تدور حول مخترق أخلاقي يحاول استغلال ثغرة أمنية لإثبات وجود الخلل.
+- اجعل "task" تطلب منه صراحة إدخال الحمولة (payload) أو العلم في حقل الإدخال.
+- يجب أن يحتوي "expectedAnswer" على نمط الحمولة أو الكود المتوقع للاستغلال (مثلاً: alert, script, onerror, hex, base64, etc.) أو العلم المطلوب.
+"""
+
+    # Non-web challenges
+    if team_role == "blue":
+        return f"""
+المستخدم هو من الفريق الأزرق (Blue Team - مدافع ومحلل أمني) في مسار الأنظمة والشبكات والتشفير والتحقيق الجنائي (غير الويب).
+يجب أن تركز المهمة والقصة والخطوات بالكامل على الجانب الدفاعي وتحليل السجلات والأنظمة وتكوينات الأمان.
+درجة الصعوبة المطلوبة للتحدي: {difficulty}
+- التحدي هنا غير معني بالويب أو الأكواد البرمجية البرونت-إند (لا توجد صفحة index.html تفاعلية).
+- المطلوب من المستخدم هو تحليل سجلات نظام أو شبكة، أو تدقيق تهيئة جدار حماية (firewall config)، أو تحليل بصمات تشفيرية (hashes/ciphers)، أو استخراج ملفات وتتبع خوادم.
+- **تنبيه هام جداً**: يجب أن تقوم بتوليد البيانات الفنية والملفات في حقل "logData" (مثل سجلات خادم Apache/Nginx، أو حزم شبكة PCAP كخيار نصي، أو سجلات الحوادث) أو في حقل "configData" (مثل ملفات تهيئة شبكة، ملفات سريّة أو نصوص برمجية بحاجة للمراجعة).
+- **إنشاء الملفات**: إذا كان التحدي يتعلق بالتشفير أو التحقيق الجنائي أو الشبكات، قم بصياغة وتمثيل محتويات الملفات البرمجية المفترضة (مثل ملف تشفير ضعيف، ملفات سجل، إلخ) وضعها بوضوح داخل "configData" كـ JSON أو نص برمجي مهيأ للمستخدم، ومثّل السجلات البرمجية في "logData" حتى يتمكن نظام محاكي Windows من تقديمها كملفات أو سجلات للمتدرب.
+- اجعل "task" تطلب منه صراحة تحليل البيانات أو قراءة الملفات والإجابة عن سؤال دفاعي محدد (مثلاً: تحديد الـ IP المهاجم، كتابة الأمر الصحيح المفقود، تحديد خوارزمية التشفير الضعيفة المستخدمة مثل md5 أو sha1، أو المنفذ المشبوه).
+- يجب أن تحتوي "expectedAnswer" على الإجابة أو الكلمة المفتاحية المباشرة والدقيقة المتوقعة للحل (مثال: md5, sha1, 192.168.1.100, port 21, etc.).
+- يجب ألا يكون المطلوب إصلاح كود HTML، بل إدخال إجابة نصية دقيقة ومباشرة في حقل الإجابة.
+"""
+    return f"""
+المستخدم هو من الفريق الأحمر (Red Team - مهاجم ومخترق) في مسار الأنظمة والشبكات والتشفير والاختراق (غير الويب).
+يجب أن تركز المهمة والقصة والخطوات بالكامل على كسر الشيفرات، تحليل السجلات، اختراق الأنظمة، وجمع المعلومات.
+درجة الصعوبة المطلوبة للتحدي: {difficulty}
+- التحدي غير معني بصفحات الويب تفاعلية، بل بتحليل الشبكات والأنظمة وفك التشفير.
+- المطلوب هو كسر تشفير ملفات، فك تشفير هاشات، البحث في سجلات الخادم، أو استغلال ثغرات المنافذ للحصول على العلم (Flag).
+- **إنشاء الملفات والتسريبات**: ضع النصوص المشفرة أو الشيفرات أو الهاشات كملفات أو مسودات فنية داخل حقل "configData" (مثال: ملف secret.enc يحتوي على نص مشفر، أو ملف hash.txt يحتوي على بصمات)، وضع السجلات الفنية للشبكة أو المنافذ في حقل "logData".
+- اجعل "task" تطلب منه بوضوح إدخال العلم المستخرج في حقل الإجابة.
+- يجب أن يحتوي "expectedAnswer" على العلم الدقيق المطلوب (مثل CyberArena{{...}}).
+"""
+
+
+# --------------------------------------------------------------------------- #
+#  Scenario ↔ DB mapping helpers                                              #
+# --------------------------------------------------------------------------- #
+
+def map_groq_scenario_to_db(groq_scenario: dict, module: str, difficulty: str) -> dict:
+    xp = groq_scenario.get("xpReward") or groq_scenario.get("xp_reward")
+    if xp is None:
+        xp = 200 if difficulty == "قوي" else 150 if difficulty == "متوسط" else 100
+    return {
+        "module": module,
+        "title": groq_scenario.get("title", ""),
+        "story": groq_scenario.get("story", ""),
+        "task_outline": (
+            groq_scenario.get("task")
+            or groq_scenario.get("taskOutline")
+            or groq_scenario.get("task_outline", "")
+        ),
+        "difficulty": groq_scenario.get("difficulty") or difficulty,
+        "xp_reward": xp,
+    }
+
+
+def map_scenario_to_list_item(scenario: dict) -> dict:
+    """Project a row into the lightweight shape used by the dashboard list."""
+    mod = scenario.get("module", "unknown")
+    info = CYBER_SECURITY_TOPICS.get(mod, {})
+    challenge_type = scenario.get("_challenge_type") or scenario.get("type") or ""
+
+    # The frontend uses `module` to route the challenge to the right editor.
+    # We override the raw `module` per challenge_type so the round-trip
+    # Dashboard → TrainingSession → backend stays type-correct.
+    if challenge_type == "vulnerability-hunter":
+        module_out = "vulnerability-hunter"
+    elif challenge_type == "code-fixing":
+        module_out = "code-fixing"
+    elif challenge_type == "log-analysis":
+        module_out = "log-analysis"
+    elif challenge_type == "web":
+        module_out = "web"
+    elif challenge_type == "crypto":
+        module_out = "crypto"
+    else:
+        module_out = mod
+
+    category = info.get("category", "Web Security")
+    if challenge_type == "vulnerability-hunter":
+        category = "Vulnerability Hunter"
+    elif challenge_type == "code-fixing":
+        category = "Code Fixing"
+    elif challenge_type == "log-analysis":
+        category = "Log Analysis"
+    elif challenge_type == "web":
+        category = "Web Security"
+    elif challenge_type == "crypto":
+        category = "Cryptography"
+
+    return {
+        "id": scenario["id"],
+        "title": scenario.get("title") or info.get("name", "سيناريو غير معروف"),
+        "module": module_out,
+        "path": info.get("path", "web-security"),
+        "category": category,
+        "difficulty": scenario.get("difficulty") or "متوسط",
+        "xpReward": scenario.get("xp_reward", 150),
+    }
+
+
+def attach_scenario_metadata(
+    training: dict,
+    scenario: dict,
+    challenge_type: Optional[str] = None,
+) -> dict:
+    """Backfill id / difficulty / xpReward / type from a scenario row.
+
+    ``challenge_type`` is the canonical challenge type
+    (``"crypto"`` / ``"web"`` / ``"code-fixing"`` / ``"log-analysis"`` /
+    ``"vulnerability-hunter"``) of the table the scenario came from.
+    It is the source of truth for ``training["type"]`` — the previous
+    behaviour fell back to ``scenario.get("module")``, which after
+    the 011 normalization migration holds the *topic* (e.g. ``xss``)
+    not the *type* (which is ``web``), so a code-fixing challenge
+    could end up with ``type="web-security"`` and route to the wrong
+    editor.
+    """
+    scenario_id = str(scenario.get("id")) if scenario.get("id") else None
+    training["id"] = scenario_id
+    training["scenarioId"] = scenario_id
+
+    if challenge_type:
+        # Authoritative: overwrite whatever Groq may have set.
+        training["type"] = challenge_type
+        training["challengeType"] = challenge_type
+    else:
+        # Fallback to the in-training value, then to the canonical
+        # module of the row's table. The list endpoint always sets
+        # ``_challenge_type`` on the row, so this only fires in
+        # legacy code paths.
+        if not training.get("type"):
+            training["type"] = scenario.get("module")
+
+    # Keep the topic (the specific subject) accessible to the editor
+    # even though we no longer use the column for routing.
+    if not training.get("topic"):
+        training["topic"] = scenario.get("topic") or scenario.get("module")
+
+    if not training.get("difficulty"):
+        training["difficulty"] = scenario.get("difficulty", "متوسط")
+    if not training.get("xpReward"):
+        training["xpReward"] = scenario.get("xp_reward", 150)
+    return training
+
+
+# --------------------------------------------------------------------------- #
+#  Background pool hooks                                                      #
+# --------------------------------------------------------------------------- #
+
+# State to keep track of rate limits and log only once
+RATE_LIMIT_ALERTED = False
+
+
+async def generate_and_store_scenario(
+    team_role: str,
+    module: str,
+    path: str = "web-security",
+    category: str = "web",
+    difficulty: str = "متوسط",
+):
+    global RATE_LIMIT_ALERTED
+    try:
+        groq_scenario = await generate_scenario_from_groq(team_role, module, path, category, difficulty)
+        db_scenario = map_groq_scenario_to_db(groq_scenario, module, difficulty)
+        await insert_scenario_to_supabase(db_scenario, team_role)
+        print(f"Background Generator: Stored a new {team_role} scenario ({difficulty}) for {module} in Supabase pool.")
+        RATE_LIMIT_ALERTED = False
+    except Exception as e:
+        if "429" in str(e) or "Rate Limit" in str(e):
+            if not RATE_LIMIT_ALERTED:
+                print("⚠️ [Groq AI] Rate Limit 429. Retrying...")
+                RATE_LIMIT_ALERTED = True
+        else:
+            import traceback
+            traceback.print_exc()
+            print(f"Background Scenario Generator Error for {team_role} - {module}: {e}")
+
+
+async def handle_background_replacement(
+    scenario_id: str,
+    team_role: str,
+    module: str,
+    path: str,
+    category: str,
+    difficulty: str,
+):
+    """Consume (delete) a solved/used challenge from the pool.
+
+    Per AGENTS.md pool architecture: the pool watcher is the ONLY
+    component allowed to call Groq for refills, and only when the pool
+    count drops to POOL_THRESHOLD. We therefore just delete and let the
+    watcher catch up later.
+    """
+    from app.core.module_router import challenge_type_for_module
+    ctype = challenge_type_for_module(module)
+    try:
+        await delete_scenario_from_supabase(scenario_id, team_role, challenge_type=ctype)
+        print(f"Deleted solved {ctype} scenario {scenario_id} from Supabase. (refill deferred to pool watcher)")
+    except Exception as e:
+        print(f"Error in background scenario replacement task: {e}")

app/services/supabase_service.py

@@ -0,0 +1,183 @@
+"""Supabase PostgREST client for the per-type challenge tables.
+
+Wraps the raw ``httpx`` calls in small, typed async functions. The
+challenge-loader / scenario-service modules build on top of these.
+"""
+
+import random
+from typing import Optional
+
+import httpx
+
+from app.core.config import SUPABASE_URL, SUPABASE_ANON_KEY
+
+
+# --------------------------------------------------------------------------- #
+#  Table routing                                                              #
+# --------------------------------------------------------------------------- #
+
+def scenario_table(team_role: str = "", challenge_type: str = "") -> str:
+    """Pick the right per-type table for a challenge lookup.
+
+    ``challenge_type`` can be one of: ``"crypto"``, ``"web"``,
+    ``"code-fixing"``, ``"log-analysis"``, ``"vulnerability-hunter"``.
+    If omitted we fall back to ``"encryption_challenges"`` for legacy
+    behavior (Blue/Red crypto).
+    """
+    if challenge_type == "web":
+        return "web_exploitation_challenges"
+    if challenge_type == "crypto":
+        return "encryption_challenges"
+    if challenge_type == "code-fixing":
+        return "code_fixing_challenges"
+    if challenge_type == "log-analysis":
+        return "log_analysis_challenges"
+    if challenge_type == "vulnerability-hunter":
+        return "vulnerability_hunter_challenges"
+    # Auto-detect (legacy callers that pass only team_role still work)
+    return "encryption_challenges"
+
+
+# --------------------------------------------------------------------------- #
+#  HTTP helpers                                                               #
+# --------------------------------------------------------------------------- #
+
+def supabase_headers(content_type: bool = False) -> dict:
+    headers = {
+        "apikey": SUPABASE_ANON_KEY,
+        "Authorization": f"Bearer {SUPABASE_ANON_KEY}",
+    }
+    if content_type:
+        headers["Content-Type"] = "application/json"
+    return headers
+
+
+# --------------------------------------------------------------------------- #
+#  Scenario CRUD                                                              #
+# --------------------------------------------------------------------------- #
+
+async def get_supabase_scenario_count(team_role: str, challenge_type: str = "") -> int:
+    if not SUPABASE_ANON_KEY or not SUPABASE_URL:
+        return 0
+    table = scenario_table(team_role, challenge_type)
+    url = f"{SUPABASE_URL}/rest/v1/{table}?select=id"
+    try:
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(url, headers=supabase_headers())
+            if resp.status_code == 200:
+                return len(resp.json())
+    except Exception as e:
+        print(f"Error checking Supabase scenario count: {e}")
+    return 0
+
+
+async def fetch_scenario_by_id(
+    team_role: str, scenario_id: str, challenge_type: str = ""
+) -> Optional[dict]:
+    if not SUPABASE_ANON_KEY or not SUPABASE_URL:
+        return None
+    table = scenario_table(team_role, challenge_type)
+    url = f"{SUPABASE_URL}/rest/v1/{table}?id=eq.{scenario_id}&team_role=eq.{team_role}"
+    try:
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(url, headers=supabase_headers())
+            if resp.status_code == 200:
+                rows = resp.json()
+                if rows:
+                    return rows[0]
+    except Exception as e:
+        print(f"Error fetching scenario {scenario_id}: {e}")
+    return None
+
+
+async def fetch_random_scenario_from_supabase(
+    team_role: str, module: str, challenge_type: str = ""
+) -> Optional[dict]:
+    if not SUPABASE_ANON_KEY or not SUPABASE_URL:
+        return None
+    table = scenario_table(team_role, challenge_type)
+    # When ``module`` is empty we deliberately skip the module filter
+    # — this is the "give me any row of this type" code path used by
+    # the dashboard list. The previous behaviour built a
+    # ``module=eq.`` clause, which matched nothing because the module
+    # column never stores an empty string.
+    params: list[str] = [f"team_role=eq.{team_role}"]
+    if module:
+        params.append(f"module=eq.{module}")
+    # Ask for a small page (PostgREST default is 1000). The pool sizes
+    # we deal with are < 30, so a single page is enough.
+    params.append("limit=50")
+    url = f"{SUPABASE_URL}/rest/v1/{table}?{'&'.join(params)}"
+    try:
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(url, headers=supabase_headers())
+            if resp.status_code == 200:
+                scenarios = resp.json()
+                if scenarios:
+                    return random.choice(scenarios)
+    except Exception as e:
+        print(f"Error fetching scenario from Supabase: {e}")
+    return None
+
+
+async def fetch_all_scenarios_for_type(
+    team_role: str, challenge_type: str = "", limit: int = 100
+) -> list[dict]:
+    """Return every row for a (team, type) pair, optionally limited.
+
+    Used by ``/api/training/list`` — the dashboard wants a complete
+    catalogue, not a random sample. The function caps the result at
+    ``limit`` (default 100) so a runaway pool can't blow up the
+    payload.
+    """
+    if not SUPABASE_ANON_KEY or not SUPABASE_URL:
+        return []
+    table = scenario_table(team_role, challenge_type)
+    url = (
+        f"{SUPABASE_URL}/rest/v1/{table}"
+        f"?team_role=eq.{team_role}&limit={int(limit)}&order=created_at.desc"
+    )
+    try:
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(url, headers=supabase_headers())
+            if resp.status_code == 200:
+                rows = resp.json()
+                return list(rows) if isinstance(rows, list) else []
+    except Exception as e:
+        print(f"Error fetching scenarios for {table}: {e}")
+    return []
+
+
+async def delete_scenario_from_supabase(
+    scenario_id: str, team_role: str, challenge_type: str = ""
+):
+    if not SUPABASE_ANON_KEY or not SUPABASE_URL:
+        return
+    table = scenario_table(team_role, challenge_type)
+    url = f"{SUPABASE_URL}/rest/v1/{table}?id=eq.{scenario_id}&team_role=eq.{team_role}"
+    try:
+        async with httpx.AsyncClient() as client:
+            await client.delete(url, headers=supabase_headers())
+    except Exception as e:
+        print(f"Error deleting scenario {scenario_id} from Supabase: {e}")
+
+
+async def insert_scenario_to_supabase(
+    scenario_data: dict, team_role: str, challenge_type: str = ""
+) -> Optional[dict]:
+    if not SUPABASE_ANON_KEY or not SUPABASE_URL:
+        return None
+    table = scenario_table(team_role, challenge_type)
+    url = f"{SUPABASE_URL}/rest/v1/{table}"
+    headers = supabase_headers(content_type=True)
+    headers["Prefer"] = "return=representation"
+    try:
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(url, json=scenario_data, headers=headers)
+            if resp.status_code in (200, 201):
+                rows = resp.json()
+                if rows:
+                    return rows[0]
+    except Exception as e:
+        print(f"Error inserting scenario to Supabase: {e}")
+    return None

app/types.py

@@ -0,0 +1,122 @@
+"""Pydantic request models, one block per concern.
+
+Kept in a single file because they're all small BaseModel definitions
+and importing them from one place makes the routers easy to scan.
+"""
+
+from typing import Optional
+from pydantic import BaseModel
+
+
+# ---------- Auth ---------- #
+
+class AuthRequest(BaseModel):
+    action: str
+    email: str
+    password: str
+    name: Optional[str] = None
+
+
+# ---------- XP ---------- #
+
+class XpRequest(BaseModel):
+    action: str
+    user_id: Optional[str] = None
+    xp_amount: Optional[int] = None
+
+
+# ---------- Training (generic / red-team web) ---------- #
+
+class TrainingRequest(BaseModel):
+    module: str
+    path: str
+    category: str
+    moduleId: Optional[str] = None
+    teamRole: Optional[str] = "red"
+    challengeId: Optional[str] = None
+
+
+class EvaluateRequest(BaseModel):
+    action: str = "evaluate"
+    originalChallenge: dict
+    userCode: str
+    teamRole: Optional[str] = "red"
+
+
+class WebEvaluateRequest(BaseModel):
+    """3-layer validation payload for web exploitation challenges (v2)."""
+    challengeId: str
+    payload: str
+    teamRole: Optional[str] = "red"
+    exploitSignal: Optional[dict] = None
+
+
+# ---------- Terminal ---------- #
+
+class TerminalRequest(BaseModel):
+    teamRole: Optional[str] = "red"
+    challengeId: str
+    command: str
+
+
+class TerminalWriteRequest(BaseModel):
+    teamRole: Optional[str] = "red"
+    challengeId: str
+    filename: str
+    content: str
+
+
+class TerminalListRequest(BaseModel):
+    teamRole: Optional[str] = "red"
+    challengeId: str
+
+
+# ---------- Certificates ---------- #
+
+class CertificateRequest(BaseModel):
+    action: str = "list"
+    user_id: str
+    category: Optional[str] = None
+    verify_code: Optional[str] = None
+    details: Optional[dict] = None
+
+
+# ---------- Solved (consume one from the pool) ---------- #
+
+class SolvedRequest(BaseModel):
+    scenarioId: str
+    module: Optional[str] = None
+    teamRole: Optional[str] = "red"
+    difficulty: Optional[str] = "متوسط"
+    path: Optional[str] = "web-security"
+    category: Optional[str] = "web"
+
+
+# ---------- Blue-team evaluators ---------- #
+
+class CodeFixEvaluateRequest(BaseModel):
+    """Request model for code-fixing challenge evaluation."""
+    challengeId: str
+    fixedCode: str
+    teamRole: Optional[str] = "blue"
+    userId: Optional[str] = None
+
+
+class LogAnalysisEvaluateRequest(BaseModel):
+    """Request model for log-analysis challenge evaluation."""
+    challengeId: str
+    attackType: str
+    attackerIp: str
+    timestamp: str
+    ioc: str
+    explanation: str = ""
+    teamRole: Optional[str] = "blue"
+    userId: Optional[str] = None
+
+
+class VulnHunterEvaluateRequest(BaseModel):
+    """Request model for vulnerability-hunter challenge evaluation."""
+    challengeId: str
+    vulnerabilityType: str
+    teamRole: Optional[str] = "blue"
+    userId: Optional[str] = None

apply_migration_005.py

@@ -1,169 +0,0 @@
-"""
-apply_migration_005.py
-======================
-Applies migration 005 to create the `web_exploitation_challenges` table.
-
-Tries three strategies in order:
-  1. Supabase Management API (requires SUPABASE_ACCESS_TOKEN env var)
-  2. Direct PostgreSQL connection (requires DATABASE_URL env var)
-  3. Fall back to: print the SQL + clipboard + step-by-step instructions
-
-Usage:
-    python apply_migration_005.py            # tries strategies 1+2 then prints
-    python apply_migration_005.py --print    # skip strategies, just print SQL
-    python apply_migration_005.py --copy     # print + copy to clipboard
-"""
-import argparse
-import os
-import sys
-import time
-from pathlib import Path
-
-# Force UTF-8 output
-sys.stdout.reconfigure(encoding="utf-8", errors="replace")
-
-# Load .env if available
-try:
-    from dotenv import load_dotenv
-    _env_path = Path(__file__).parent / ".env"
-    if _env_path.exists():
-        load_dotenv(_env_path)
-except ImportError:
-    pass
-
-MIGRATION_FILE = Path(__file__).parent / "migrations" / "005_web_exploitation_challenges.sql"
-SUPABASE_URL = os.environ.get("SUPABASE_URL", "https://yevtnyokixocpihpdwqu.supabase.co")
-SUPABASE_PROJECT_ID = SUPABASE_URL.replace("https://", "").replace("http://", "").split(".")[0]
-SUPABASE_ACCESS_TOKEN = os.environ.get("SUPABASE_ACCESS_TOKEN", "")
-DATABASE_URL = os.environ.get("DATABASE_URL", "")
-
-
-def banner(msg: str) -> None:
-    print()
-    print("=" * 70)
-    print(f"  {msg}")
-    print("=" * 70)
-
-
-def print_sql() -> None:
-    print(MIGRATION_FILE.read_text(encoding="utf-8"))
-
-
-def try_supabase_management_api() -> bool:
-    """Strategy 1: use the Supabase Management API to run SQL.
-
-    Requires a personal access token from https://supabase.com/dashboard/account/tokens
-    in SUPABASE_ACCESS_TOKEN env var.
-    """
-    if not SUPABASE_ACCESS_TOKEN:
-        return False
-
-    import httpx
-
-    banner("Strategy 1: Supabase Management API")
-    print(f"Project: {SUPABASE_PROJECT_ID}")
-
-    sql = MIGRATION_FILE.read_text(encoding="utf-8")
-    url = f"https://api.supabase.com/v1/projects/{SUPABASE_PROJECT_ID}/database/query"
-    headers = {
-        "Authorization": f"Bearer {SUPABASE_ACCESS_TOKEN}",
-        "Content-Type": "application/json",
-    }
-    try:
-        with httpx.Client(timeout=30) as client:
-            resp = client.post(url, headers=headers, json={"query": sql})
-            if resp.status_code == 200:
-                print("✓ Migration applied via Management API")
-                return True
-            else:
-                print(f"✗ Management API returned {resp.status_code}: {resp.text[:200]}")
-                return False
-    except Exception as e:
-        print(f"✗ Management API failed: {e}")
-        return False
-
-
-def try_direct_postgres() -> bool:
-    """Strategy 2: connect directly to the Postgres database.
-
-    Requires DATABASE_URL env var (e.g. postgresql://postgres:PASS@db.PROJECT.supabase.co:5432/postgres)
-    Find this in Supabase Dashboard > Settings > Database > Connection string.
-    """
-    if not DATABASE_URL:
-        return False
-
-    banner("Strategy 2: Direct Postgres connection")
-    try:
-        import psycopg2
-    except ImportError:
-        print("✗ psycopg2 not installed. Run: pip install psycopg2-binary")
-        return False
-
-    sql = MIGRATION_FILE.read_text(encoding="utf-8")
-    try:
-        conn = psycopg2.connect(DATABASE_URL)
-        conn.autocommit = True
-        with conn.cursor() as cur:
-            cur.execute(sql)
-        conn.close()
-        print("✓ Migration applied via direct Postgres connection")
-        return True
-    except Exception as e:
-        print(f"✗ Direct Postgres failed: {e}")
-        return False
-
-
-def fallback_manual() -> None:
-    """Strategy 3: print the SQL and clear instructions."""
-    banner("Strategy 3: Manual — paste into Supabase SQL Editor")
-    print()
-    print("The migration SQL is printed below.")
-    print("To apply it manually:")
-    print(f"  1. Open: https://supabase.com/dashboard/project/{SUPABASE_PROJECT_ID}/sql/new")
-    print("  2. Paste the SQL into the editor")
-    print("  3. Click 'Run' (or press Ctrl+Enter)")
-    print()
-    print("-" * 70)
-    print_sql()
-    print("-" * 70)
-
-    # Optionally copy to clipboard (Windows)
-    if "--copy" in sys.argv:
-        try:
-            import subprocess
-            sql = MIGRATION_FILE.read_text(encoding="utf-8")
-            p = subprocess.Popen(["clip"], stdin=subprocess.PIPE, shell=True)
-            p.communicate(sql.encode("utf-16le"))
-            print("\n✓ SQL copied to clipboard")
-        except Exception as e:
-            print(f"\n(Clipboard copy failed: {e})")
-
-
-def main():
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--print", action="store_true", help="Only print the SQL, skip auto-apply")
-    parser.add_argument("--copy", action="store_true", help="Print + copy to clipboard")
-    args = parser.parse_args()
-
-    banner("CyberArena — Migration 005 (web_exploitation_challenges)")
-
-    if args.print:
-        print_sql()
-        return
-
-    # Try automatic strategies first
-    if try_supabase_management_api():
-        return
-    if try_direct_postgres():
-        return
-
-    # Fall back to manual
-    fallback_manual()
-
-    print()
-    print("After applying the migration, restart the backend.")
-    print("The [webex:red] pool watcher will populate 5 challenges within ~8 seconds.")
-
-
-if __name__ == "__main__":
-    main()

apply_migration_009.py

@@ -1,208 +0,0 @@
-"""
-Apply migration 009 (1v1 mode tables) to the Supabase project.
-
-================================================================
-3 ways to run this. Pick one:
-================================================================
-
-A) RECOMMENDED — one-shot via the Supabase SQL editor
-   1. Open https://app.supabase.com/project/yevtnyokixocpihpdwqu/sql/new
-   2. Paste the contents of backend/migrations/009_onevone_mode.sql
-   3. Click "Run"
-   (no service key needed, takes 5 seconds)
-
-B) AUTOMATIC — this script, if you set SUPABASE_SERVICE_KEY in backend/.env
-   Get the key from: https://app.supabase.com/project/yevtnyokixocpihpdwqu/settings/api
-   → service_role / secret (NOT the anon key)
-
-C) PSQL DIRECT — if you have the postgres connection string
-   psql "postgresql://postgres:[PASSWORD]@db.yevtnyokixocpihpdwqu.supabase.co:5432/postgres" \
-        -f backend/migrations/009_onevone_mode.sql
-
-================================================================
-The script tries method B first, then falls back to printing the SQL
-for method A. It's idempotent — every CREATE uses IF NOT EXISTS.
-================================================================
-"""
-
-import os
-import sys
-import httpx
-from dotenv import load_dotenv
-
-backend_dir = os.path.dirname(os.path.abspath(__file__))
-load_dotenv(dotenv_path=os.path.join(backend_dir, ".env"))
-
-SUPABASE_URL = os.environ.get("SUPABASE_URL", "https://yevtnyokixocpihpdwqu.supabase.co").rstrip("/")
-SUPABASE_ANON_KEY = os.environ.get("SUPABASE_ANON_KEY", "")
-SUPABASE_SERVICE_KEY = os.environ.get("SUPABASE_SERVICE_KEY", "").strip()
-MIGRATION_PATH = os.path.join(backend_dir, "migrations", "009_onevone_mode.sql")
-
-
-def read_sql() -> str:
-    with open(MIGRATION_PATH, "r", encoding="utf-8") as f:
-        return f.read()
-
-
-def split_sql(sql: str) -> list[str]:
-    """Split a SQL script into individual statements (semi-colon separated,
-    ignoring those inside $$ ... $$ blocks)."""
-    statements: list[str] = []
-    buf: list[str] = []
-    in_dollar = False
-    for raw in sql.splitlines():
-        line = raw
-        if line.strip().startswith("--") and not buf:
-            continue
-        buf.append(line)
-        if "$$" in line:
-            in_dollar = not in_dollar
-        if line.rstrip().endswith(";") and not in_dollar:
-            stmt = "\n".join(buf).strip().rstrip(";").strip()
-            if stmt:
-                statements.append(stmt)
-            buf = []
-    if buf:
-        tail = "\n".join(buf).strip().rstrip(";").strip()
-        if tail:
-            statements.append(tail)
-    return statements
-
-
-def try_pg_endpoint(path: str, headers: dict, statements: list[str]) -> bool:
-    url = f"{SUPABASE_URL}{path}"
-    print(f"  → trying {url}")
-    try:
-        with httpx.Client(timeout=60) as client:
-            for i, stmt in enumerate(statements, 1):
-                preview = stmt.splitlines()[0][:70]
-                r = client.post(url, headers=headers, json={"query": stmt})
-                if r.status_code in (200, 201):
-                    print(f"    [{i}/{len(statements)}] OK    {preview}")
-                else:
-                    body = r.text[:200]
-                    if " PGREST205" in body or "schema cache" in body or "must be owner" in body:
-                        return False
-                    print(f"    [{i}/{len(statements)}] FAIL  HTTP {r.status_code}  {preview}")
-                    print(f"             {body}")
-                    return False
-        return True
-    except Exception as e:
-        print(f"  → network error: {e}")
-        return False
-
-
-def apply_via_pg_meta() -> bool:
-    if not SUPABASE_SERVICE_KEY:
-        return False
-    sql = read_sql()
-    statements = split_sql(sql)
-    print(f"Attempting pg-meta apply with {len(statements)} statements ...")
-    headers = {
-        "apikey": SUPABASE_SERVICE_KEY,
-        "Authorization": f"Bearer {SUPABASE_SERVICE_KEY}",
-        "Content-Type": "application/json",
-    }
-    # try common paths
-    for path in ("/pg/query", "/pg-meta/query", "/rest/v1/rpc/exec_sql"):
-        if try_pg_endpoint(path, headers, statements):
-            return True
-    return False
-
-
-def apply_via_management_api() -> bool:
-    """Try the Supabase management API (requires access token, not service key)."""
-    access = os.environ.get("SUPABASE_ACCESS_TOKEN", "").strip()
-    if not access:
-        return False
-    project_ref = SUPABASE_URL.split("//")[-1].split(".")[0]
-    url = f"https://api.supabase.com/v1/projects/{project_ref}/database/query"
-    sql = read_sql()
-    headers = {
-        "Authorization": f"Bearer {access}",
-        "Content-Type": "application/json",
-    }
-    print(f"Attempting Management API apply ...")
-    try:
-        with httpx.Client(timeout=60) as client:
-            r = client.post(url, headers=headers, json={"query": sql})
-            if r.status_code in (200, 201):
-                print(f"  → OK")
-                return True
-            print(f"  → HTTP {r.status_code}: {r.text[:200]}")
-    except Exception as e:
-        print(f"  → network error: {e}")
-    return False
-
-
-def show_manual_steps() -> None:
-    print()
-    print("=" * 70)
-    print("MANUAL STEPS (5 seconds, no token needed)")
-    print("=" * 70)
-    print()
-    print("1. Open this URL in your browser:")
-    print(f"   https://app.supabase.com/project/{SUPABASE_URL.split('//')[-1].split('.')[0]}/sql/new")
-    print()
-    print("2. Paste the following SQL:")
-    print("-" * 70)
-    print(read_sql())
-    print("-" * 70)
-    print()
-    print("3. Click 'Run' (or press Ctrl+Enter)")
-    print()
-    print("4. Re-run this script to verify:")
-    print("   python apply_migration_009.py --verify")
-    print()
-
-
-def verify() -> bool:
-    """Hit a known table via PostgREST to confirm it exists."""
-    if not SUPABASE_ANON_KEY:
-        print("!! SUPABASE_ANON_KEY missing — cannot verify")
-        return False
-    tables = [
-        "onevone_rooms", "onevone_players",
-        "onevone_matches", "onevone_submissions",
-    ]
-    headers = {
-        "apikey": SUPABASE_ANON_KEY,
-        "Authorization": f"Bearer {SUPABASE_ANON_KEY}",
-    }
-    all_ok = True
-    print("Verifying 1v1 tables exist ...")
-    with httpx.Client(timeout=20) as client:
-        for t in tables:
-            r = client.get(f"{SUPABASE_URL}/rest/v1/{t}?select=id&limit=1", headers=headers)
-            if r.status_code == 200:
-                print(f"  [OK]  {t}")
-            else:
-                body = r.text[:120].replace("\n", " ")
-                print(f"  [!!]  {t}  → HTTP {r.status_code}: {body}")
-                all_ok = False
-    return all_ok
-
-
-def main() -> int:
-    if "--verify" in sys.argv:
-        return 0 if verify() else 2
-
-    if not os.path.exists(MIGRATION_PATH):
-        print(f"!! migration file not found: {MIGRATION_PATH}")
-        return 1
-
-    if apply_via_pg_meta():
-        print("\n[OK] Migration applied via pg-meta.")
-        verify()
-        return 0
-    if apply_via_management_api():
-        print("\n[OK] Migration applied via management API.")
-        verify()
-        return 0
-
-    show_manual_steps()
-    return 2
-
-
-if __name__ == "__main__":
-    sys.exit(main())

challenge_files/blue_android-ios_1780374909_app_logs.txt

@@ -1,3 +0,0 @@
-2023-02-15 14:30:00 - Sent data to 192.168.1.100:8080
-2023-02-15 14:31:00 - Received response from 192.168.1.100:8080
-2023-02-15 14:32:00 - Sent data to 192.168.1.101:8080

challenge_files/blue_binary-analysis_1780074195_MalwareX.exe

@@ -1 +0,0 @@
-00000000 4d 5a 90 00 03 00 00 00 04 00 00 00 ff ff 00 00

challenge_files/blue_binary-analysis_1780439585_MalwareX.exe

@@ -1,16 +0,0 @@
-00000000  4d 5a 90 00 03 00 00 00  04 00 00 00 ff ff 00 00  |MZ..............|
-00000010  b8 00 00 00 00 00 00 00  40 00 00 00 00 00 00 00  |........@.......|
-00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
-00000030  00 00 00 00 00 00 00 00  00 10 00 00 00 02 00 00  |................|
-00000040  14 01 00 00 00 10 00 00  00 00 00 00 00 00 00 00  |................|
-00000050  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
-00000060  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
-00000070  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
-00000080  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
-00000090  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
-000000a0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
-000000b0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
-000000c0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
-000000d0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
-000000e0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
-000000f0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

challenge_files/blue_cloud-config_1780424632_docker-compose.yml

@@ -1 +0,0 @@
-version: '3'<br/>services:<br/>  web:<br/>    build: .<br/>    ports:<br/>      - "80:80"<br/>    volumes:<br/>      - .:/app

challenge_files/blue_csrf_1780074134_index.html

@@ -1 +0,0 @@
-<!DOCTYPE html><html><head><title>تعديل الملفات الشخصية</title></head><body><h1>تعديل الملفات الشخصية</h1><form action="/edit-profile" method="post"><input type="hidden" name="csrf_token" value="1234567890"><input type="text" name="username" placeholder="اسم المستخدم"><input type="email" name="email" placeholder="البريد الإلكتروني"><input type="password" name="password" placeholder="كلمة المرور"><button type="submit">حفظ التغييرات</button></form></body></html>

challenge_files/blue_dns-poisoning_1780073949_dns-logs.txt

@@ -1,3 +0,0 @@
-2023-02-16 14:30:00, 192.168.1.100, 8.8.8.8, A, apex.com, 192.168.1.200
-2023-02-16 14:31:00, 192.168.1.101, 8.8.8.8, A, apex.com, 192.168.1.201
-2023-02-16 14:32:00, 192.168.1.102, 8.8.8.8, A, apex.com, 192.168.1.202

challenge_files/blue_encryption-basics_1780073989_encrypted_message.txt

@@ -1 +0,0 @@
-GUR PENML XRL VF ZL FRPERG CBFG

challenge_files/blue_encryption-basics_1780074215_hashes.txt

@@ -1 +0,0 @@
-098f6bcd4621d373cade4e832627b4f6

challenge_files/blue_encryption-basics_1780430362_encryption_logs.txt

@@ -1,3 +0,0 @@
-2022-01-01 12:00:00 - ملف1.txt - md5
-2022-01-01 12:05:00 - ملف2.txt - sha1
-2022-01-01 12:10:00 - ملف3.txt - md5

challenge_files/blue_encryption-basics_1780439473_file.enc

@@ -1 +0,0 @@
-md5_hash_here