* Add Documentation

Author: White4Shadow

documentation/README.md

@@ -0,0 +1,244 @@
+# OnlyLeveling Documentation
+
+## Table of Contents
+
+1. [Introduction](#1-introduction)  
+2. [Architecture Overview](#2-architecture-overview)  
+3. [Installation](#3-installation)  
+   - [3.1. Clone the Repository](#31-clone-the-repository)  
+   - [3.2. Running the Service](#32-running-the-service)  
+   - [3.3. Running the Checker](#33-running-the-checker)  
+4. [Usage](#4-usage)  
+5. [Exploits and Fixes](#5-exploits-and-fixes)  
+   - [5.1. Directory Traversal in File Access](#51-directory-traversal-in-file-access)  
+   - [5.2. Collision-Prone Seed Hash for Item IDs](#52-collisionprone-seed-hash-for-item-ids)  
+   - [5.3. Insecure JWT SECRET_KEY Generation](#53-insecure-jwt-secret_key-generation)  
+6. [File Structure](#6-file-structure)  
+   - [6.1. Checker](#61-checker)  
+   - [6.2. Service](#62-service)
+
+---
+
+## 1. Introduction
+
+**OnlyLeveling** is a multiplayer RPG-style web application where players progress by opening lootboxes, creating/playing dungeons, battling others, and leveling up. The system includes a frontend, backend, and a seed generator component used for item ID derivation.
+
+**Main functionalities:**
+- Register & Login  
+- Open Lootboxes to obtain Items  
+- Create & Play Dungeons  
+- Fight other players  
+- Gain XP and level up
+
+---
+
+## 2. Architecture Overview
+
+OnlyLeveling consists of several components:
+
+- **Frontend (Port 2627):** Player-facing UI for authentication, lootboxes, dungeons, PvP, and inventory management.  
+- **Backend (Port 2626):** Core API for auth, item management, dungeon logic, battles, and file serving (e.g., `/images/{filename}`).  
+- **SeedGen (Port 2628):** Item seed/hash helper used to derive ItemIDs. Note: Since the main functionality for this service is written in OPAL I used Python to handle Connections to this service.
+- **Checker (Port 12627):** External process that interacts with the service to validate behavior and flag availability.
+
+---
+
+## 3. Installation
+
+### 3.1. Clone the Repository
+
+```bash
+git clone https://github.com/enowars/enowars9-service-only-leveling.git
+cd enowars9-service-only-leveling
+```
+
+### 3.2. Running the Service
+
+From the project root (see the `service/` folder), start the stack (frontend, backend, seedgen).
+
+```bash
+cd Service
+docker compose up --build -d
+```
+
+- **Frontend:** http://localhost:2627  
+- **Backend:**  http://localhost:2626  
+- **SeedGen:**  http://localhost:2628
+
+### 3.3. Running the Checker
+
+From the `checker/` directory:
+
+```bash
+cd checker
+docker compose up --build -d
+```
+
+- **Checker:** reachable on port **12627**
+
+---
+
+## 4. Usage
+
+Once running:
+### Registration and Login
+#### Open the **Frontend** at `http://localhost:2627/` to register/login.  
+![Register Screen](./assets/registerpage.png)
+![Login Screen](./assets/loginpage.png)
+#### After Logging in you will see the **Dashboard** with your current Level /XP
+![Dashboard Screen](./assets/dashboard.png)
+### Items Page - Opening a Lootbox and Saving notes
+#### Switch to the "Items"-Page. Use the **"Open Lootbox!"** Button clicking on it to obtain items (max. 2). 
+![Items Screen](./assets/itemspage_unnopened.png)
+#### After Opening a Lootbox you will see your obtained Items here
+![Items Screen](./assets/itemspage_opened.png)
+#### With a click on the "Edit"-icon you will be able to type in and save a note
+![Items Screen](./assets/itemspage_notesaved.png)
+### Create Dungeon
+#### Switch to the **Create Dungeon Page**. Before creating your own dungeon you also can upload a own image for it
+![Create Dungeon Screen](./assets/createdungeonpage.png)
+#### After that you can just fill in the required Dungeon information and create you own dungeon
+### Play Dungeons
+#### Switch to the **"Dungeons" Page**. here you will see already existing Dungeons and Dungeons you created your own. To Play a Dungeon simply click on **"Enter Dungeon"**. You will gain XP for successful entered Dungeons.
+![Play Dungeon Screen](./assets/dungeonpage.png)
+### Fight other Players
+#### Switch to the **Fight Page**. Here you can simply select your opponent in the Drop-Down-List and click **"Fight!"** to fight them
+![Fight Players Screen](./assets/fightpage.png)
+#### After the Fight you will see if you won the fight, the items used by each player and the amount of XP you've earned.
+#### Having more power than the opponent will lead to an Win and having less will lead to an Loose
+![Fight Players Screen](./assets/fightpage_afterfight.png)
+### Leaderboard
+#### There is also a Leaderboard where you can see the Top players (Name, Level & Power)
+![Leaderboard Screen](./assets/leaderboard.png)
+#### Clicking on **"view"** will result on a detailed vie of the respective user.
+![Leaderboard Screen](./assets/dashboard.png)
+
+---
+
+## 5. Exploits and Fixes
+This service contains 2 Flagstores with 3 possible exploit Pathes.
+
+### 5.1 Directory Traversal in File Access
+
+**Issue**  
+The route `/images/{filename}` does not adequately validate the `filename` parameter since the method uses **":path"**:
+```bash
+@app.get("/images/{filename:path}")
+```
+Inputs containing path traversal tokens can break out of the intended directory.
+
+**Flag location**  
+A **JPG** in another user’s upload directory contains the flag (steganographically embedded with `steghide`).
+
+**Exploit steps:**  
+1. Upload image to have your own directory created
+2. Send crafted request to `/images/%2e%2e/[USERNAME]/stegano.jpg` using directory traversal.  
+2. Save `stegano.jpg`.  
+3. Extract flag:
+   ```bash
+   steghide extract -sf [image_path] -xf [flagfile_path] -p
+   ```
+
+**Fix:** Remove ":path" from method, restrict filenames, normalize and check paths or serve files by ID.
+
+**Example-Fix:** 
+   ```bash
+   #service/backend/main.py
+   def is_safe_filename(filename):
+    if ".." in filename or "/" in filename or "\\" in filename or "\x00" in filename:
+        return False
+    if not re.match(r'^[\w\-. ]+$', filename):
+        return False
+    return True
+
+@app.get("/images/{filename}")
+async def get_private_dungeon_image(
+    filename: str,
+    current_user: schemas.User = Depends(get_current_active_user)
+):
+    if not is_safe_filename(filename):
+        raise HTTPException(status_code=400, detail="Invalid filename.")
+
+    user_dir = os.path.abspath(os.path.join(UPLOADS_DIR, current_user.username))
+    abs_file_path = os.path.abspath(os.path.join(user_dir, filename))
+    real_file_path = os.path.realpath(abs_file_path)
+
+    if os.path.commonpath([real_file_path, user_dir]) != user_dir:
+        raise HTTPException(status_code=404, detail="Image not found or you do not have permission to access it.")
+
+    if not os.path.isfile(real_file_path):
+        raise HTTPException(status_code=404, detail="Image not found or you do not have permission to access it.")
+
+    return FileResponse(
+        real_file_path
+    )
+   ```
+---
+
+### 5.2 Collision-Prone Seed Hash for Item IDs
+
+**Issue**  
+Weak arithmetic with small modulo causes collisions. Attackers can choose usernames mapping to same ItemID as target.
+
+**Flag location**  
+Flag in **Item Note** of item with colliding ID.
+
+**Exploit steps:**  
+1. Reverse seed function.  
+2. Pick username with matching ItemID.
+3. Login and open Lootbox with respective user
+3. Read flagged Item Note.
+
+**Fix:** Use a secure UUID/random generator
+
+**Example-Fix:** 
+```bash
+#service/backend/main.py
+random.getrandbits(14)
+```
+or use "**Random**"-Structure of the Opal lib
+
+---
+
+### 5.3 Insecure JWT SECRET_KEY Generation
+
+**Issue**  
+`SECRET_KEY` is derived from time and truncated to 2 chars. Predictable => JWT forgery.
+
+**Flag location**  
+With forged JWT, attacker logs in as target account to access images/items.
+
+**Exploit steps:**  
+1. Reconstruct `SECRET_KEY`.  
+2. Forge JWT for target.  
+3. Download secret image / read Item Note.
+
+**Fix:** Use strong random secret, rotate regularly, harden token validation.
+**Example-Fix:** 
+```bash
+#service/backend/generate_secret.sh
+SECRET=$(openssl rand -hex 32)
+```
+---
+
+## 6. File Structure
+
+### 6.1 Checker
+
+```
+checker
+├── docker-compose.yaml         # Docker compose file
+└── src                         # Checker source code
+    ├── checker.py              # Main checker script
+```
+
+### 6.2 Service
+
+```
+Service
+├── backend/                    # Core API
+    ├── main.py                 # Contains Routes and Logic
+├── cleanup/                    # Maintenance Service (Cleanup DB)
+├── frontend/                   # Web UI for user interaction
+└── seed/                       # SeedGen for item ID and JWT Secret derivation
+```