Hall of Legends Pre set up

.github/copilot-instructions.md

@@ -1,17 +1,18 @@
 # Copilot Instructions
-## General Guidelines
-minimal changes to existing code
-preserve functionality when possible
-clear and concise comments
-no plan unless specified
-no compile unless specified
-no test unless specified
-if testing is specified:
-    MSTest framework
-    UV is used
-avoid New Dependencies
 
+## General Guidelines
+- Minimal changes to existing code
+- Preserve functionality when possible
+- Clear and concise comments
+- No plan unless specified
+- No compile unless specified
+- No test unless specified
+- If testing is specified:
+    - MSTest framework
+    - UV is used
+- Avoid new dependencies
 
 ## Project-Specific Rules
 - Remove AI generation of wordlists and audio system from the basic codebase
-- Keep challenge mode/HF storage and PWA support in the basic codebase
+- Keep challenge mode/HF storage and PWA support in the basic codebase
+- Implement Hall functionality using existing HF-backed storage patterns (no new local data file) and route it via `?page=hall` instead of leaderboard naming

README.md

@@ -61,8 +61,13 @@ BattleWords is a vocabulary learning game inspired by classic Battleship mechani
 - 10 incorrect guess limit per game
 - Two game modes: Classic (chain guesses) and Too Easy (single guess per reveal)
 
+### Hall of Legends
+- Legendary runs (`score >= 46`) can be saved to Hall of Legends from the game-over flow.
+- Hall page is available in development and production at `?page=hall`.
+- Hall JSON is compatible with Wrdler leaderboard schema (`challenge_id`, `entry_type`, `users`, etc.) with `entry_type` set to `hall`.
+
 ### Visuals
-- Ocean-themed gradient background with wave animations
+- Ocean-themed gradient background with wave animations are removed
 - Responsive UI built with Streamlit
 
 ### Word lists
@@ -130,7 +135,43 @@ docker run -p8501:8501 battlewords
 ```
 
 ### Environment Variables
-None required.
+- `HF_API_TOKEN` (required for HF-backed Hall save/load in deployed environments)
+- `HF_REPO_ID` (HF dataset/repo used by storage helpers)
+- `SHORTENER_JSON_FILE` (optional, default: `shortener.json`)
+- `HALL_OF_LEGENDS_FILE` (optional, Hall JSON path in HF repo)
+
+### Hall of Legends JSON Example (compatible)
+
+```json
+{
+  "challenge_id": "hall-of-legends/classic-classic-12x12",
+  "entry_type": "hall",
+  "game_mode": "classic",
+  "grid_size": 12,
+  "puzzle_options": {
+    "spacer": 1,
+    "may_overlap": false
+  },
+  "users": [
+    {
+      "uid": "20260325T184512Z-A9K2QW",
+      "username": "Charles",
+      "word_list": ["BLADE", "SHORE", "MARKET", "TUNNEL", "RIBBON", "CANDLE"],
+      "score": 49,
+      "time": 132.447291,
+      "timestamp": "2026-03-25T18:45:12.902145+00:00",
+      "word_list_difficulty": 112.3849012231
+    }
+  ],
+  "created_at": "2026-03-25T18:45:13.111942+00:00",
+  "version": "0.2.40",
+  "show_incorrect_guesses": true,
+  "enable_free_letters": false,
+  "wordlist_source": "classic.txt",
+  "game_title": "Battlewords",
+  "max_display_entries": 30
+}
+```
 
 ## Folder Structure
 

battlewords/modules/constants.py

@@ -68,6 +68,16 @@ def load_settings() -> Dict[str, Any]:
 # Load settings at module level for easy import
 APP_SETTINGS = load_settings()
 
+# ---------------------------------------------------------------------------
+# Hugging Face Storage Configuration
+# ---------------------------------------------------------------------------
+
+HF_API_TOKEN = os.getenv("HF_API_TOKEN", "")
+HF_REPO_ID = os.getenv("HF_REPO_ID", "")
+SHORTENER_JSON_FILE = os.getenv("SHORTENER_JSON_FILE", "shortener.json")
+SPACE_NAME = os.getenv("SPACE_NAME", "Surn/BattleWords")
+HALL_OF_LEGENDS_FILE = os.getenv("HALL_OF_LEGENDS_FILE", "games/hall_of_legends.json")
+
 
 # ---------------------------------------------------------------------------
 # Temporary Directory Configuration

battlewords/modules/storage.md

@@ -0,0 +1,268 @@
+# Storage Module (`modules/storage.py`) Usage Guide
+
+The `storage.py` module provides helper functions for:
+- Generating permalinks for 3D viewer projects.
+- Uploading files in batches to a Hugging Face repository.
+- Managing URL shortening by storing (short URL, full URL) pairs in a JSON file on the repository.
+- Retrieving full URLs from short URL IDs and vice versa.
+- Handle specific file types for 3D models, images, video and audio.
+- **📁 Listing folders and files in HuggingFace repositories.**
+- **🔑 Cryptographic key management for Open Badge 3.0 issuers.**
+
+## Key Functions
+
+### 1. `generate_permalink(valid_files, base_url_external, permalink_viewer_url="surn-3d-viewer.hf.space")`
+- **Purpose:**  
+  Given a list of file paths, it looks for exactly one model file (with an extension defined in `model_extensions`) and exactly two image files (extensions defined in `image_extensions`). If the criteria are met, it returns a permalink URL built from the base URL and query parameters.
+- **Usage Example:**from modules.storage import generate_permalink
+
+valid_files = [
+    "models/3d_model.glb",
+    "images/model_texture.png",
+    "images/model_depth.png"
+]
+base_url_external = "https://huggingface.co/datasets/Surn/Storage/resolve/main/saved_models/my_model"
+permalink = generate_permalink(valid_files, base_url_external)
+if permalink:
+    print("Permalink:", permalink)
+### 2. `generate_permalink_from_urls(model_url, hm_url, img_url, permalink_viewer_url="surn-3d-viewer.hf.space")`
+- **Purpose:**  
+  Constructs a permalink URL by combining individual URLs for a 3D model (`model_url`), height map (`hm_url`), and image (`img_url`) into a single URL with corresponding query parameters.
+- **Usage Example:**from modules.storage import generate_permalink_from_urls
+
+model_url = "https://example.com/model.glb"
+hm_url = "https://example.com/heightmap.png"
+img_url = "https://example.com/source.png"
+
+permalink = generate_permalink_from_urls(model_url, hm_url, img_url)
+print("Generated Permalink:", permalink)
+### 3. `upload_files_to_repo(files, repo_id, folder_name, create_permalink=False, repo_type="dataset", permalink_viewer_url="surn-3d-viewer.hf.space")`
+- **Purpose:**  
+  Uploads a batch of files (each file represented as a path string) to a specified Hugging Face repository (e.g. `"Surn/Storage"`) under a given folder.
+  The function's return type is `Union[Dict[str, Any], List[Tuple[Any, str]]]`.
+  - When `create_permalink` is `True` and exactly three valid files (one model and two images) are provided, the function returns a dictionary:{
+    "response": <upload_folder_response>,
+    "permalink": "<full_permalink_url>",
+    "short_permalink": "<shortened_permalink_url_with_sid>"
+}  - Otherwise (or if `create_permalink` is `False` or conditions for permalink creation are not met), it returns a list of tuples, where each tuple is `(upload_folder_response, individual_file_link)`.
+  - If no valid files are provided, it returns an empty list `[]` (this case should ideally also return the dictionary with empty/None values for consistency, but currently returns `[]` as per the code).
+- **Usage Example:**
+
+  **a. Uploading with permalink creation:**from modules.storage import upload_files_to_repo
+
+files_for_permalink = [
+    "local/path/to/model.glb",
+    "local/path/to/heightmap.png",
+    "local/path/to/image.png"
+]
+repo_id = "Surn/Storage" # Make sure this is defined, e.g., from constants or environment variables
+folder_name = "my_new_model_with_permalink"
+
+upload_result = upload_files_to_repo(
+    files_for_permalink, 
+    repo_id, 
+    folder_name, 
+    create_permalink=True
+)
+
+if isinstance(upload_result, dict):
+    print("Upload Response:", upload_result.get("response"))
+    print("Full Permalink:", upload_result.get("permalink"))
+    print("Short Permalink:", upload_result.get("short_permalink"))
+elif upload_result: # Check if list is not empty
+    print("Upload Response for individual files:")
+    for res, link in upload_result:
+        print(f"  Response: {res}, Link: {link}")
+else:
+    print("No files uploaded or error occurred.")
+  **b. Uploading without permalink creation (or if conditions for permalink are not met):**from modules.storage import upload_files_to_repo
+
+files_individual = [
+    "local/path/to/another_model.obj",
+    "local/path/to/texture.jpg"
+]
+repo_id = "Surn/Storage"
+folder_name = "my_other_uploads"
+
+upload_results_list = upload_files_to_repo(
+    files_individual, 
+    repo_id, 
+    folder_name, 
+    create_permalink=False # Or if create_permalink=True but not 1 model & 2 images
+)
+
+if upload_results_list: # Will be a list of tuples
+    print("Upload results for individual files:")
+    for res, link in upload_results_list:
+        print(f"  Upload Response: {res}, File Link: {link}")
+else:
+    print("No files uploaded or error occurred.")
+### 4. URL Shortening Functions: `gen_full_url(...)` and Helpers
+The module also enables URL shortening by managing a JSON file (e.g. `shortener.json`) in a Hugging Face repository. It supports CRUD-like operations:
+- **Read:** Look up the full URL using a provided short URL ID.
+- **Create:** Generate a new short URL ID for a full URL if no existing mapping exists.
+- **Update/Conflict Handling:**  
+If both short URL ID and full URL are provided, it checks consistency and either confirms or reports a conflict.
+
+#### `gen_full_url(short_url=None, full_url=None, repo_id=None, repo_type="dataset", permalink_viewer_url="surn-3d-viewer.hf.space", json_file="shortener.json")`
+- **Purpose:**  
+  Based on which parameter is provided, it retrieves or creates a mapping between a short URL ID and a full URL.  
+  - If only `short_url` (the ID) is given, it returns the corresponding `full_url`.  
+  - If only `full_url` is given, it looks up an existing `short_url` ID or generates and stores a new one.  
+  - If both are given, it validates and returns the mapping or an error status.
+- **Returns:** A tuple `(status_message, result_url)`, where `status_message` indicates the outcome (e.g., `"success_retrieved_full"`, `"created_short"`) and `result_url` is the relevant URL (full or short ID).
+- **Usage Examples:**
+
+  **a. Convert a full URL into a short URL ID:**from modules.storage import gen_full_url
+from modules.constants import HF_REPO_ID, SHORTENER_JSON_FILE # Assuming these are defined
+
+full_permalink = "https://surn-3d-viewer.hf.space/?3d=https%3A%2F%2Fexample.com%2Fmodel.glb&hm=https%3A%2F%2Fexample.com%2Fheightmap.png&image=https%3A%2F%2Fexample.com%2Fsource.png"
+
+status, short_id = gen_full_url(
+    full_url=full_permalink, 
+    repo_id=HF_REPO_ID, 
+    json_file=SHORTENER_JSON_FILE
+)
+print("Status:", status)
+if status == "created_short" or status == "success_retrieved_short":
+    print("Shortened URL ID:", short_id)
+    # Construct the full short URL for sharing:
+    # permalink_viewer_url = "surn-3d-viewer.hf.space" # Or from constants
+    # shareable_short_url = f"https://{permalink_viewer_url}/?sid={short_id}"
+    # print("Shareable Short URL:", shareable_short_url)
+  **b. Retrieve the full URL from a short URL ID:**from modules.storage import gen_full_url
+from modules.constants import HF_REPO_ID, SHORTENER_JSON_FILE # Assuming these are defined
+
+short_id_to_lookup = "aBcDeFg1"  # Example short URL ID
+
+status, retrieved_full_url = gen_full_url(
+    short_url=short_id_to_lookup, 
+    repo_id=HF_REPO_ID, 
+    json_file=SHORTENER_JSON_FILE
+)
+print("Status:", status)
+if status == "success_retrieved_full":
+    print("Retrieved Full URL:", retrieved_full_url)
+## 📁 Repository Folder Listing Functions
+
+### 5. `_list_repo_folders(repo_id, path_prefix, repo_type="dataset")`
+- **Purpose:**  
+  List folder names under a given path in a HuggingFace repository. Enables folder-based discovery without index files.
+- **Parameters:**
+  - `repo_id` (str): The repository ID on Hugging Face
+  - `path_prefix` (str): The path prefix to list folders under
+  - `repo_type` (str): Repository type. Default is `"dataset"`.
+- **Returns:** `List[str]` - List of folder names found under the path_prefix.
+- **Usage Example:**
+```python
+from modules.storage import _list_repo_folders
+
+# List all date folders in daily leaderboards
+folders = _list_repo_folders("Surn/Wrdler-Data", "games/leaderboards/daily")
+print("Available dates:", folders)
+# Output: ['2025-01-27', '2025-01-26', '2025-01-25']
+```
+
+### 6. `_list_repo_files_in_folder(repo_id, folder_path, repo_type="dataset")`
+- **Purpose:**  
+  List file names directly under a folder in a HuggingFace repository.
+- **Parameters:**
+  - `repo_id` (str): The repository ID on Hugging Face
+  - `folder_path` (str): The folder path to list files under
+  - `repo_type` (str): Repository type. Default is `"dataset"`.
+- **Returns:** `List[str]` - List of file names found directly in the folder.
+- **Usage Example:**
+```python
+from modules.storage import _list_repo_files_in_folder
+
+files = _list_repo_files_in_folder(
+    "Surn/Wrdler-Data",
+    "games/leaderboards/daily/2025-01-27/classic-classic-0"
+)
+print("Files:", files)
+# Output: ['settings.json']
+```
+
+## 🔑 Cryptographic Key Management Functions
+
+### 7. `store_issuer_keypair(issuer_id, public_key, private_key, repo_id=None)`
+- **Purpose:**  
+  Securely store cryptographic keys for an issuer in a private Hugging Face repository. Private keys are encrypted before storage.
+- **⚠️ IMPORTANT:** This function requires a PRIVATE Hugging Face repository to ensure the security of stored private keys. Never use this with public repositories.
+- **Storage Structure:**keys/issuers/{issuer_id}/
+├── private_key.json (encrypted)
+└── public_key.json- **Returns:** `bool` - True if keys were stored successfully, False otherwise.
+- **Usage Example:**from modules.storage import store_issuer_keypair
+
+# Example Ed25519 keys (multibase encoded)
+issuer_id = "https://example.edu/issuers/565049"
+public_key = "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
+private_key = "z3u2MQhLnQw7nvJRGJCdKdqfXHV4N7BLKuEGFWnJqsVSdgYv"
+
+success = store_issuer_keypair(issuer_id, public_key, private_key)
+if success:
+    print("Keys stored successfully")
+else:
+    print("Failed to store keys")
+### 8. `get_issuer_keypair(issuer_id, repo_id=None)`
+- **Purpose:**  
+  Retrieve and decrypt stored cryptographic keys for an issuer from the private Hugging Face repository.
+- **⚠️ IMPORTANT:** This function accesses a PRIVATE Hugging Face repository containing encrypted private keys. Ensure proper access control and security measures.
+- **Returns:** `Tuple[Optional[str], Optional[str]]` - (public_key, private_key) or (None, None) if not found.
+- **Usage Example:**from modules.storage import get_issuer_keypair
+
+issuer_id = "https://example.edu/issuers/565049"
+public_key, private_key = get_issuer_keypair(issuer_id)
+
+if public_key and private_key:
+    print("Keys retrieved successfully")
+    print(f"Public key: {public_key}")
+    # Use private_key for signing operations
+else:
+    print("Keys not found or error occurred")
+### 9. `get_verification_methods_registry(repo_id=None)`
+- **Purpose:**  
+  Retrieve the global verification methods registry containing all registered issuer public keys.
+- **Returns:** `Dict[str, Any]` - Registry data containing all verification methods.
+- **Usage Example:**from modules.storage import get_verification_methods_registry
+
+registry = get_verification_methods_registry()
+methods = registry.get("verification_methods", [])
+
+for method in methods:
+    print(f"Issuer: {method['issuer_id']}")
+    print(f"Public Key: {method['public_key']}")
+    print(f"Key Type: {method['key_type']}")
+    print("---")
+### 10. `list_issuer_ids(repo_id=None)`
+- **Purpose:**  
+  List all issuer IDs that have stored keys in the repository.
+- **Returns:** `List[str]` - List of issuer IDs.
+- **Usage Example:**from modules.storage import list_issuer_ids
+
+issuer_ids = list_issuer_ids()
+print("Registered issuers:")
+for issuer_id in issuer_ids:
+    print(f"  - {issuer_id}")
+## Notes
+- **Authentication:** All functions that interact with Hugging Face Hub use the HF API token defined as `HF_API_TOKEN` in `modules/constants.py`. Ensure this environment variable is correctly set.
+- **Constants:** Functions like `gen_full_url` and `upload_files_to_repo` (when creating short links) rely on `HF_REPO_ID` and `SHORTENER_JSON_FILE` from `modules/constants.py` for the URL shortening feature.
+- **🔐 Private Repository Requirement:** Key management functions require a PRIVATE Hugging Face repository to ensure the security of stored encrypted private keys. Never use these functions with public repositories.
+- **File Types:** Only files with extensions included in `upload_file_types` (a combination of `model_extensions` and `image_extensions` from `modules/constants.py`) are processed by `upload_files_to_repo`.
+- **Repository Configuration:** When using URL shortening, file uploads, and key management, ensure that the specified Hugging Face repository (e.g., defined by `HF_REPO_ID`) exists and that you have write permissions.
+- **Temporary Directory:** `upload_files_to_repo` temporarily copies files to a local directory (configured by `TMPDIR` in `modules/constants.py`) before uploading.
+- **Key Encryption:** Private keys are encrypted using basic XOR encryption (demo implementation). In production environments, upgrade to proper encryption like Fernet from the cryptography library.
+- **Error Handling:** Functions include basic error handling (e.g., catching `RepositoryNotFoundError`, `EntryNotFoundError`, JSON decoding errors, or upload issues) and print messages to the console for debugging. Review function return values to handle these cases appropriately in your application.
+
+## 🔒 Security Considerations for Key Management
+
+1. **Private Repository Only:** Always use private repositories for key storage to protect cryptographic material.
+2. **Key Sanitization:** Issuer IDs are sanitized for file system compatibility (replacing special characters with underscores).
+3. **Encryption:** Private keys are encrypted before storage. Upgrade to Fernet encryption in production.
+4. **Access Control:** Implement proper authentication and authorization for key access.
+5. **Key Rotation:** Consider implementing key rotation mechanisms for enhanced security.
+6. **Audit Logging:** Monitor key access and usage patterns for security auditing.
+
+---
+
+This guide provides the essential usage examples for interacting with the storage, URL-shortening, folder listing, and cryptographic key management functionality. You can integrate these examples into your application or use them as a reference when extending functionality.

battlewords/modules/storage.py

@@ -0,0 +1,799 @@
+# modules/storage.py
+__version__ = "0.1.6"
+import os
+import urllib.parse
+import tempfile
+import shutil
+import json
+import base64
+import logging
+from datetime import datetime, timezone
+from huggingface_hub import login, upload_folder, hf_hub_download, HfApi
+from huggingface_hub.utils import RepositoryNotFoundError, EntryNotFoundError
+from .constants import HF_API_TOKEN, upload_file_types, model_extensions, image_extensions, audio_extensions, video_extensions, doc_extensions, HF_REPO_ID, SHORTENER_JSON_FILE
+from typing import Any, Dict, List, Tuple, Union, Optional
+
+# Configure professional logging
+logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
+logger = logging.getLogger(__name__)
+
+# see storage.md for detailed information about the storage module and its functions.
+
+def generate_permalink(valid_files, base_url_external, permalink_viewer_url="surn-3d-viewer.hf.space"):
+    """
+    Given a list of valid files, checks if they contain exactly 1 model file and 2 image files.
+    Constructs and returns a permalink URL with query parameters if the criteria is met.
+    Otherwise, returns None.
+    """
+    model_link = None
+    images_links = []
+    audio_links = []
+    video_links = []
+    doc_links = []
+    for f in valid_files:
+        filename = os.path.basename(f)
+        ext = os.path.splitext(filename)[1].lower()
+        if ext in model_extensions:
+            if model_link is None:
+                model_link = f"{base_url_external}/{filename}"
+        elif ext in image_extensions:
+            images_links.append(f"{base_url_external}/{filename}")
+        elif ext in audio_extensions:
+            audio_links.append(f"{base_url_external}/{filename}")
+        elif ext in video_extensions:
+            video_links.append(f"{base_url_external}/{filename}")
+        elif ext in doc_extensions:
+            doc_links.append(f"{base_url_external}/{filename}")
+    if model_link and len(images_links) == 2:
+        # Construct a permalink to the viewer project with query parameters.
+        permalink_viewer_url = f"https://{permalink_viewer_url}/"
+        params = {"3d": model_link, "hm": images_links[0], "image": images_links[1]}
+        query_str = urllib.parse.urlencode(params)
+        return f"{permalink_viewer_url}?{query_str}"
+    return None
+
+def generate_permalink_from_urls(model_url, hm_url, img_url, permalink_viewer_url="surn-3d-viewer.hf.space"):
+    """
+    Constructs and returns a permalink URL with query string parameters for the viewer.
+    Each parameter is passed separately so that the image positions remain consistent.
+    
+    Parameters:
+        model_url (str): Processed URL for the 3D model.
+        hm_url (str): Processed URL for the height map image.
+        img_url (str): Processed URL for the main image.
+        permalink_viewer_url (str): The base viewer URL.
+    
+    Returns:
+        str: The generated permalink URL.
+    """
+    import urllib.parse
+    params = {"3d": model_url, "hm": hm_url, "image": img_url}
+    query_str = urllib.parse.urlencode(params)
+    return f"https://{permalink_viewer_url}/?{query_str}"
+
+def upload_files_to_repo(
+    files: List[Any],
+    repo_id: str,
+    folder_name: str,
+    create_permalink: bool = False,
+    repo_type: str = "dataset",
+    permalink_viewer_url: str = "surn-3d-viewer.hf.space"
+) -> Union[Dict[str, Any], List[Tuple[Any, str]]]:
+    """
+    Uploads multiple files to a Hugging Face repository using a batch upload approach via upload_folder.
+
+    Parameters:
+        files (list): A list of file paths (str) to upload.
+        repo_id (str): The repository ID on Hugging Face for storage, e.g. "Surn/Storage".
+        folder_name (str): The subfolder within the repository where files will be saved.
+        create_permalink (bool): If True and if exactly three files are uploaded (1 model and 2 images),
+                                 returns a single permalink to the project with query parameters.
+                                 Otherwise, returns individual permalinks for each file.
+        repo_type (str): Repository type ("space", "dataset", etc.). Default is "dataset".
+        permalink_viewer_url (str): The base viewer URL.
+
+    Returns:
+        Union[Dict[str, Any], List[Tuple[Any, str]]]:
+            If create_permalink is True and files match the criteria:
+                dict: {
+                    "response": <upload response>,
+                    "permalink": <full_permalink URL>,
+                    "short_permalink": <shortened permalink URL>
+                }
+            Otherwise:
+                list: A list of tuples (response, permalink) for each file.
+    """
+    logger.info(f"📤 Starting batch upload to repository: {repo_id}")
+    logger.debug(f"📁 Target folder: {folder_name}")
+    logger.debug(f"🔗 Create permalink: {create_permalink}")
+    
+    # Log in using the HF API token.
+    try:
+        login(token=HF_API_TOKEN)
+        logger.debug("🔑 Authenticated with Hugging Face")
+    except Exception as e:
+        logger.error(f"🚫 Authentication failed: {e}")
+        return {"response": "Authentication failed", "permalink": None, "short_permalink": None} if create_permalink else []
+    
+    valid_files = []
+    permalink_short = None
+    
+    # Ensure folder_name does not have a trailing slash.
+    folder_name = folder_name.rstrip("/")
+    
+    # Filter for valid files based on allowed extensions.
+    logger.debug("🔍 Filtering valid files...")
+    for f in files:
+        file_name = f if isinstance(f, str) else f.name if hasattr(f, "name") else None
+        if file_name is None:
+            continue
+        ext = os.path.splitext(file_name)[1].lower()
+        if ext in upload_file_types:
+            valid_files.append(f)
+            logger.debug(f"✅ Valid file: {os.path.basename(file_name)}")
+        else:
+            logger.debug(f"⚠️ Skipped file with invalid extension: {os.path.basename(file_name)}")
+    
+    logger.info(f"📊 Found {len(valid_files)} valid files out of {len(files)} total")
+    
+    if not valid_files:
+        logger.warning("⚠️ No valid files to upload")
+        if create_permalink:
+            return {
+                "response": "No valid files to upload.",
+                "permalink": None,
+                "short_permalink": None
+            }
+        return [] 
+    
+    # Create a temporary directory and copy valid files
+    logger.debug("📁 Creating temporary directory for batch upload...")
+    with tempfile.TemporaryDirectory(dir=os.getenv("TMPDIR", "/tmp")) as temp_dir:
+        for file_path in valid_files:
+            filename = os.path.basename(file_path)
+            dest_path = os.path.join(temp_dir, filename)
+            shutil.copy(file_path, dest_path)
+            logger.debug(f"📄 Copied: {filename}")
+        
+        logger.info("🚀 Starting batch upload to Hugging Face...")
+        # Batch upload all files in the temporary folder.
+        try:
+            response = upload_folder(
+                folder_path=temp_dir,
+                repo_id=repo_id,
+                repo_type=repo_type,
+                path_in_repo=folder_name,
+                commit_message="Batch upload files"
+            )
+            logger.info("✅ Batch upload completed successfully")
+        except Exception as e:
+            logger.error(f"❌ Batch upload failed: {e}")
+            return {"response": f"Upload failed: {e}", "permalink": None, "short_permalink": None} if create_permalink else []
+    
+    # Construct external URLs for each uploaded file.
+    base_url_external = f"https://huggingface.co/datasets/{repo_id}/resolve/main/{folder_name}"
+    individual_links = []
+    for file_path in valid_files:
+        filename = os.path.basename(file_path)
+        link = f"{base_url_external}/{filename}"
+        individual_links.append(link)
+        logger.debug(f"🔗 Generated link: {link}")
+    
+    # Handle permalink creation if requested
+    if create_permalink:
+        logger.info("🔗 Attempting to create permalink...")
+        permalink = generate_permalink(valid_files, base_url_external, permalink_viewer_url)
+        if permalink:
+            logger.info(f"✅ Generated permalink: {permalink}")
+            logger.debug("🔗 Creating short URL...")
+            status, short_id = gen_full_url(
+                full_url=permalink,
+                repo_id=HF_REPO_ID,
+                json_file=SHORTENER_JSON_FILE
+            )
+            if status in ["created_short", "success_retrieved_short", "exists_match"]:
+                permalink_short = f"https://{permalink_viewer_url}/?sid={short_id}"
+                logger.info(f"✅ Created short permalink: {permalink_short}")
+            else:
+                permalink_short = None 
+                logger.warning(f"⚠️ URL shortening failed: {status} for {permalink}")
+
+            return {
+                "response": response,
+                "permalink": permalink,
+                "short_permalink": permalink_short
+            }
+        else:
+            logger.warning("⚠️ Permalink generation failed (criteria not met)")
+            return {
+                "response": response,
+                "permalink": None,
+                "short_permalink": None
+            }
+
+    # Return individual tuples for each file
+    logger.info(f"📋 Returning individual links for {len(individual_links)} files")
+    return [(response, link) for link in individual_links]
+
+def _generate_short_id(length=8):
+    """Generates a random base64 URL-safe string."""
+    return base64.urlsafe_b64encode(os.urandom(length * 2))[:length].decode('utf-8')
+
+def _get_json_from_repo(repo_id, json_file_name, repo_type="dataset"):
+    """Downloads and loads the JSON file from the repo. Returns empty list if not found or error."""
+    try:
+        login(token=HF_API_TOKEN)
+        json_path = hf_hub_download(
+            repo_id=repo_id,
+            filename=json_file_name,
+            repo_type=repo_type,
+            token=HF_API_TOKEN
+        )
+        with open(json_path, 'r') as f:
+            data = json.load(f)
+        os.remove(json_path)
+        return data
+    except RepositoryNotFoundError:
+        logger.warning(f"Repository {repo_id} not found.")
+        return []
+    except EntryNotFoundError:
+        logger.warning(f"JSON file {json_file_name} not found in {repo_id}. Initializing with empty list.")
+        return []
+    except json.JSONDecodeError:
+        logger.error(f"Error decoding JSON from {json_file_name}. Returning empty list.")
+        return []
+    except Exception as e:
+        logger.error(f"An unexpected error occurred while fetching {json_file_name}: {e}")
+        return []
+
+def _get_files_from_repo(repo_id, file_name, repo_type="dataset"):
+    """Downloads and loads the file from the repo. File must be in upload_file_types. Returns empty list if not found or error."""
+    filename = os.path.basename(file_name)
+    ext = os.path.splitext(file_name)[1].lower() 
+    if ext not in upload_file_types:
+        logger.error(f"File {filename} with extension {ext} is not allowed for upload.")
+        return None
+    else:
+        try:
+            login(token=HF_API_TOKEN)
+            file_path = hf_hub_download(
+                repo_id=repo_id,
+                filename=file_name,
+                repo_type=repo_type,
+                token=HF_API_TOKEN
+            )
+            if not file_path:
+                return None
+            return file_path
+        except RepositoryNotFoundError:
+            logger.warning(f"Repository {repo_id} not found.")
+            return None
+        except EntryNotFoundError:
+            logger.warning(f"file {file_name} not found in {repo_id}. Initializing with empty list.")
+            return None
+        except Exception as e:
+            logger.error(f"Error fetching {file_name} from {repo_id}: {e}")
+            return None
+
+def _upload_json_to_repo(data, repo_id, json_file_name, repo_type="dataset"):
+    """Uploads the JSON data to the specified file in the repo."""
+    try:
+        login(token=HF_API_TOKEN)
+        api = HfApi()
+        # Use a temporary directory specified by TMPDIR or default to system temp
+        temp_dir_for_json = os.getenv("TMPDIR", tempfile.gettempdir())
+        os.makedirs(temp_dir_for_json, exist_ok=True)
+
+        with tempfile.NamedTemporaryFile(mode="w+", delete=False, suffix=".json", dir=temp_dir_for_json) as tmp_file:
+            json.dump(data, tmp_file, indent=2)
+            tmp_file_path = tmp_file.name
+        
+        logger.info(f"📤 Uploading JSON data to {json_file_name}...")
+        api.upload_file(
+            path_or_fileobj=tmp_file_path,
+            path_in_repo=json_file_name,
+            repo_id=repo_id,
+            repo_type=repo_type,
+            commit_message=f"Update {json_file_name}"
+        )
+        os.remove(tmp_file_path) # Clean up temporary file
+        logger.info("✅ JSON data uploaded successfully")
+        return True
+    except Exception as e:
+        logger.error(f"Failed to upload {json_file_name} to {repo_id}: {e}")
+        if 'tmp_file_path' in locals() and os.path.exists(tmp_file_path):
+            os.remove(tmp_file_path) # Ensure cleanup on error too
+        return False
+
+def _find_url_in_json(data, short_url=None, full_url=None):
+    """
+    Searches the JSON data.
+    If short_url is provided, returns the corresponding full_url or None.
+    If full_url is provided, returns the corresponding short_url or None.
+    """
+    if not data: # Handles cases where data might be None or empty
+        return None
+    if short_url:
+        for item in data:
+            if item.get("short_url") == short_url:
+                return item.get("full_url")
+    if full_url:
+        for item in data:
+            if item.get("full_url") == full_url:
+                return item.get("short_url")
+    return None
+
+def _add_url_to_json(data, short_url, full_url):
+    """Adds a new short_url/full_url pair to the data. Returns updated data."""
+    if data is None: 
+        data = []
+    data.append({"short_url": short_url, "full_url": full_url})
+    return data
+
+def gen_full_url(short_url=None, full_url=None, repo_id=None, repo_type="dataset", permalink_viewer_url="surn-3d-viewer.hf.space", json_file="shortener.json"):
+    """
+    Manages short URLs and their corresponding full URLs in a JSON file stored in a Hugging Face repository.
+
+    - If short_url is provided, attempts to retrieve and return the full_url.
+    - If full_url is provided, attempts to retrieve an existing short_url or creates a new one, stores it, and returns the short_url.
+    - If both are provided, checks for consistency or creates a new entry.
+    - If neither is provided, or repo_id is missing, returns an error status.
+
+    Returns:
+        tuple: (status_message, result_url)
+               status_message can be "success", "created", "exists", "error", "not_found".
+               result_url is the relevant URL (short or full) or None if an error occurs or not found.
+    """
+    if not repo_id:
+        return "error_repo_id_missing", None
+    if not short_url and not full_url:
+        return "error_no_input", None
+
+    login(token=HF_API_TOKEN) # Ensure login at the beginning
+    url_data = _get_json_from_repo(repo_id, json_file, repo_type)
+
+    # Case 1: Only short_url provided (lookup full_url)
+    if short_url and not full_url:
+        found_full_url = _find_url_in_json(url_data, short_url=short_url)
+        return ("success_retrieved_full", found_full_url) if found_full_url else ("not_found_short", None)
+
+    # Case 2: Only full_url provided (lookup or create short_url)
+    if full_url and not short_url:
+        existing_short_url = _find_url_in_json(url_data, full_url=full_url)
+        if existing_short_url:
+            return "success_retrieved_short", existing_short_url
+        else:
+            # Create new short_url
+            new_short_id = _generate_short_id()
+            url_data = _add_url_to_json(url_data, new_short_id, full_url)
+            if _upload_json_to_repo(url_data, repo_id, json_file, repo_type):
+                return "created_short", new_short_id 
+            else:
+                return "error_upload", None
+
+    # Case 3: Both short_url and full_url provided
+    if short_url and full_url:
+        found_full_for_short = _find_url_in_json(url_data, short_url=short_url)
+        found_short_for_full = _find_url_in_json(url_data, full_url=full_url)
+
+        if found_full_for_short == full_url: 
+            return "exists_match", short_url 
+        if found_full_for_short is not None and found_full_for_short != full_url: 
+            return "error_conflict_short_exists_different_full", short_url
+        if found_short_for_full is not None and found_short_for_full != short_url:
+            return "error_conflict_full_exists_different_short", found_short_for_full
+        
+        # If short_url is provided and not found, or full_url is provided and not found,
+        # or neither is found, then create a new entry with the provided short_url and full_url.
+        # This effectively allows specifying a custom short_url if it's not already taken.
+        url_data = _add_url_to_json(url_data, short_url, full_url)
+        if _upload_json_to_repo(url_data, repo_id, json_file, repo_type):
+            return "created_specific_pair", short_url
+        else:
+            return "error_upload", None
+                 
+    return "error_unhandled_case", None # Should not be reached
+
+def _encrypt_private_key(private_key: str, password: str = None) -> str:
+    """
+    Basic encryption for private keys. In production, use proper encryption like Fernet.
+    
+    Note: This is a simplified encryption for demonstration. In production environments,
+    use proper encryption libraries like cryptography.fernet.Fernet with secure key derivation.
+    
+    Args:
+        private_key (str): The private key to encrypt
+        password (str, optional): Password for encryption. If None, uses a default method.
+    
+    Returns:
+        str: Base64 encoded encrypted private key
+    """
+    # WARNING: This is a basic XOR encryption for demo purposes only
+    # In production, use proper encryption like Fernet from cryptography library
+    if not password:
+        password = "default_encryption_key"  # In production, use secure key derivation
+    
+    encrypted_bytes = []
+    for i, char in enumerate(private_key):
+        encrypted_bytes.append(ord(char) ^ ord(password[i % len(password)]))
+    
+    encrypted_data = bytes(encrypted_bytes)
+    return base64.b64encode(encrypted_data).decode('utf-8')
+
+def _decrypt_private_key(encrypted_private_key: str, password: str = None) -> str:
+    """
+    Basic decryption for private keys. In production, use proper decryption like Fernet.
+    
+    Args:
+        encrypted_private_key (str): Base64 encoded encrypted private key
+        password (str, optional): Password for decryption. If None, uses a default method.
+    
+    Returns:
+        str: Decrypted private key
+    """
+    # WARNING: This is a basic XOR decryption for demo purposes only
+    if not password:
+        password = "default_encryption_key"  # In production, use secure key derivation
+    
+    encrypted_data = base64.b64decode(encrypted_private_key)
+    decrypted_chars = []
+    for i, byte in enumerate(encrypted_data):
+        decrypted_chars.append(chr(byte ^ ord(password[i % len(password)])))
+    
+    return ''.join(decrypted_chars)
+
+def store_issuer_keypair(issuer_id: str, public_key: str, private_key: str, repo_id: str = None) -> bool:
+    """
+    Store cryptographic keys for an issuer in the private Hugging Face repository.
+    
+    **IMPORTANT: This function requires a PRIVATE Hugging Face repository to ensure
+    the security of stored private keys. Never use this with public repositories.**
+    
+    The keys are stored in the following structure:
+    keys/issuers/{issuer_id}/
+    ├── private_key.json (encrypted)
+    └── public_key.json
+    
+    Args:
+        issuer_id (str): Unique identifier for the issuer (e.g., "https://example.edu/issuers/565049")
+        public_key (str): Multibase-encoded public key
+        private_key (str): Multibase-encoded private key (will be encrypted before storage)
+        repo_id (str, optional): Repository ID. If None, uses HF_REPO_ID from constants.
+    
+    Returns:
+        bool: True if keys were stored successfully, False otherwise
+    
+    Raises:
+        ValueError: If issuer_id, public_key, or private_key are empty
+        Exception: If repository operations fail
+    
+    Example:
+        >>> public_key = "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
+        >>> private_key = "z3u2MQhLnQw7nvJRGJCdKdqfXHV4N7BLKuEGFWnJqsVSdgYv"
+        >>> success = store_issuer_keypair("https://example.edu/issuers/565049", public_key, private_key)
+        >>> print(f"Keys stored: {success}")
+    """
+    if not issuer_id or not public_key or not private_key:
+        logger.error("❌ Missing required parameters: issuer_id, public_key, and private_key are required")
+        raise ValueError("issuer_id, public_key, and private_key are required")
+    
+    if not repo_id:
+        repo_id = HF_REPO_ID
+        logger.debug(f"🔧 Using default repository: {repo_id}")
+    
+    # Sanitize issuer_id for use as folder name
+    safe_issuer_id = issuer_id.replace("https://", "").replace("http://", "").replace("/", "_").replace(":", "_")
+    logger.info(f"🔑 Storing keypair for issuer: {issuer_id}")
+    logger.debug(f"🗂️ Safe issuer ID: {safe_issuer_id}")
+    
+    try:
+        # Encrypt the private key before storage
+        encrypted_private_key = _encrypt_private_key(private_key)
+        logger.debug("🔐 Private key encrypted successfully")
+        
+        # Prepare key data structures
+        private_key_data = {
+            "issuer_id": issuer_id,
+            "encrypted_private_key": encrypted_private_key,
+            "key_type": "Ed25519VerificationKey2020",
+            "created_at": datetime.now(timezone.utc).isoformat(),
+            "encryption_method": "basic_xor"  # In production, use proper encryption
+        }
+        
+        public_key_data = {
+            "issuer_id": issuer_id,
+            "public_key": public_key,
+            "key_type": "Ed25519VerificationKey2020",
+            "created_at": datetime.now(timezone.utc).isoformat()
+        }
+        
+        logger.info("📤 Uploading private key...")
+        # Store private key
+        private_key_path = f"keys/issuers/{safe_issuer_id}/private_key.json"
+        private_key_success = _upload_json_to_repo(private_key_data, repo_id, private_key_path, "dataset")
+        
+        logger.info("📤 Uploading public key...")
+        # Store public key
+        public_key_path = f"keys/issuers/{safe_issuer_id}/public_key.json"
+        public_key_success = _upload_json_to_repo(public_key_data, repo_id, public_key_path, "dataset")
+        
+        # Update global verification methods registry
+        if private_key_success and public_key_success:
+            logger.info("📋 Updating verification methods registry...")
+            _update_verification_methods_registry(issuer_id, safe_issuer_id, public_key, repo_id)
+            logger.info("✅ Keypair stored successfully and registry updated")
+        else:
+            logger.error("❌ Failed to store one or both keys")
+        
+        return private_key_success and public_key_success
+        
+    except Exception as e:
+        logger.error(f"💥 Error storing issuer keypair for {issuer_id}: {e}")
+        return False
+
+def get_issuer_keypair(issuer_id: str, repo_id: str = None) -> Tuple[Optional[str], Optional[str]]:
+    """
+    Retrieve stored cryptographic keys for an issuer from the private Hugging Face repository.
+    
+    **IMPORTANT: This function accesses a PRIVATE Hugging Face repository containing
+    encrypted private keys. Ensure proper access control and security measures.**
+
+        Args:
+        issuer_id (str): Unique identifier for the issuer
+        repo_id (str, optional): Repository ID. If None, uses HF_REPO_ID from constants.
+    
+    Returns:
+        Tuple[Optional[str], Optional[str]]: (public_key, private_key) or (None, None) if not found
+        
+    Raises:
+        ValueError: If issuer_id is empty
+        Exception: If repository operations fail or decryption fails
+    
+    Example:
+        >>> public_key, private_key = get_issuer_keypair("https://example.edu/issuers/565049")
+        >>> if public_key and private_key:
+        ...     print("Keys retrieved successfully")
+        ... else:
+        ...     print("Keys not found")
+    """
+    if not issuer_id:
+        logger.error("❌ issuer_id is required")
+        raise ValueError("issuer_id is required")
+    
+    if not repo_id:
+        repo_id = HF_REPO_ID
+        logger.debug(f"🔧 Using default repository: {repo_id}")
+    
+    # Sanitize issuer_id for use as folder name
+    safe_issuer_id = issuer_id.replace("https://", "").replace("http://", "").replace("/", "_").replace(":", "_")
+    logger.info(f"🔍 Retrieving keypair for issuer: {issuer_id}")
+    logger.debug(f"🗂️ Safe issuer ID: {safe_issuer_id}")
+    
+    try:
+        logger.debug("📥 Retrieving public key...")
+        # Retrieve public key
+        public_key_path = f"keys/issuers/{safe_issuer_id}/public_key.json"
+        public_key_data = _get_json_from_repo(repo_id, public_key_path, "dataset")
+        
+        logger.debug("📥 Retrieving private key...")
+        # Retrieve private key
+        private_key_path = f"keys/issuers/{safe_issuer_id}/private_key.json"
+        private_key_data = _get_json_from_repo(repo_id, private_key_path, "dataset")
+        
+        if not public_key_data or not private_key_data:
+            logger.warning(f"⚠️ Keys not found for issuer {issuer_id}")
+            return None, None
+        
+        # Extract and decrypt private key
+        encrypted_private_key = private_key_data.get("encrypted_private_key")
+        if not encrypted_private_key:
+            logger.error(f"❌ No encrypted private key found for issuer {issuer_id}")
+            return None, None
+        
+        logger.debug("🔓 Decrypting private key...")
+        decrypted_private_key = _decrypt_private_key(encrypted_private_key)
+        public_key = public_key_data.get("public_key")
+        
+        logger.info(f"✅ Successfully retrieved keypair for issuer {issuer_id}")
+        return public_key, decrypted_private_key
+        
+    except Exception as e:
+        logger.error(f"💥 Error retrieving issuer keypair for {issuer_id}: {e}")
+        return None, None
+
+def _update_verification_methods_registry(issuer_id: str, safe_issuer_id: str, public_key: str, repo_id: str):
+    """
+    Update the global verification methods registry with new issuer public key.
+    
+    Args:
+        issuer_id (str): Original issuer ID
+        safe_issuer_id (str): Sanitized issuer ID for file system
+        public_key (str): Public key to register
+        repo_id (str): Repository ID
+    """
+    try:
+        registry_path = "keys/global/verification_methods.json"
+        registry_data = _get_json_from_repo(repo_id, registry_path, "dataset")
+        
+        if not registry_data:
+            registry_data = {"verification_methods": []}
+        
+        # Check if issuer already exists in registry
+        existing_entry = None
+        for i, method in enumerate(registry_data.get("verification_methods", [])):
+            if method.get("issuer_id") == issuer_id:
+                existing_entry = i
+                break
+        
+        # Create new verification method entry
+        verification_method = {
+            "issuer_id": issuer_id,
+            "safe_issuer_id": safe_issuer_id,
+            "public_key": public_key,
+            "key_type": "Ed25519VerificationKey2020",
+            "updated_at": datetime.now(timezone.utc).isoformat()
+        }
+        
+        if existing_entry is not None:
+            # Update existing entry
+            registry_data["verification_methods"][existing_entry] = verification_method
+            logger.info(f"♻️ Updated verification method for issuer {issuer_id}")
+        else:
+            # Add new entry
+            registry_data["verification_methods"].append(verification_method)
+            logger.info(f"➕ Added new verification method for issuer {issuer_id}")
+        
+        # Upload updated registry
+        _upload_json_to_repo(registry_data, repo_id, registry_path, "dataset")
+        logger.info("✅ Verification methods registry updated successfully")
+        
+    except Exception as e:
+        logger.error(f"Error updating verification methods registry: {e}")
+
+def get_verification_methods_registry(repo_id: str = None) -> Dict[str, Any]:
+    """
+    Retrieve the global verification methods registry.
+    
+    Args:
+        repo_id (str, optional): Repository ID. If None, uses HF_REPO_ID from constants.
+    
+    Returns:
+        Dict[str, Any]: Registry data containing all verification methods
+    """
+    if not repo_id:
+        repo_id = HF_REPO_ID
+    
+    try:
+        registry_path = "keys/global/verification_methods.json"
+        registry_data = _get_json_from_repo(repo_id, registry_path, "dataset")
+        return registry_data if registry_data else {"verification_methods": []}
+    except Exception as e:
+        logger.error(f"Error retrieving verification methods registry: {e}")
+        return {"verification_methods": []}
+
+def list_issuer_ids(repo_id: str = None) -> List[str]:
+    """
+    List all issuer IDs that have stored keys in the repository.
+    
+    Args:
+        repo_id (str, optional): Repository ID. If None, uses HF_REPO_ID from constants.
+    
+    Returns:
+        List[str]: List of issuer IDs
+    """
+    if not repo_id:
+        repo_id = HF_REPO_ID
+    
+    try:
+        registry = get_verification_methods_registry(repo_id)
+        return [method["issuer_id"] for method in registry.get("verification_methods", [])]
+    except Exception as e:
+        logger.error(f"Error listing issuer IDs: {e}")
+        return []
+
+def _list_repo_folders(repo_id: str, path_prefix: str, repo_type: str = "dataset") -> List[str]:
+    """
+    List folder names under a given path in a HuggingFace repository.
+    
+    Args:
+        repo_id: The repository ID on Hugging Face
+        path_prefix: The path prefix to list folders under (e.g., "leaderboards/daily/2025-01-27")
+        repo_type: Repository type ("dataset", "model", "space"). Default is "dataset".
+    
+    Returns:
+        List of folder names (not full paths) found under the path_prefix.
+        Returns empty list if path not found or on error.
+    """
+    try:
+        login(token=HF_API_TOKEN)
+        api = HfApi()
+        
+        # List all files in the repo under the prefix
+        # The list_repo_files returns file paths, so we extract unique folder names
+        all_files = api.list_repo_files(
+            repo_id=repo_id,
+            repo_type=repo_type,
+            token=HF_API_TOKEN
+        )
+        
+        # Ensure path_prefix ends with /
+        if path_prefix and not path_prefix.endswith("/"):
+            path_prefix = path_prefix + "/"
+        
+        folders = set()
+        for file_path in all_files:
+            if file_path.startswith(path_prefix):
+                # Get the relative path after the prefix
+                relative_path = file_path[len(path_prefix):]
+                # Extract the first folder name (before any /)
+                if "/" in relative_path:
+                    folder_name = relative_path.split("/")[0]
+                    folders.add(folder_name)
+        
+        return sorted(list(folders))
+    
+    except RepositoryNotFoundError:
+        logger.warning(f"Repository {repo_id} not found.")
+        return []
+    except Exception as e:
+        logger.error(f"Error listing folders in {repo_id}/{path_prefix}: {e}")
+        return []
+
+
+def _list_repo_files_in_folder(repo_id: str, folder_path: str, repo_type: str = "dataset") -> List[str]:
+    """
+    List file names (not full paths) directly under a folder in a HuggingFace repository.
+    
+    Args:
+        repo_id: The repository ID on Hugging Face
+        folder_path: The folder path to list files under
+        repo_type: Repository type. Default is "dataset".
+    
+    Returns:
+        List of file names found directly in the folder.
+    """
+    try:
+        login(token=HF_API_TOKEN)
+        api = HfApi()
+        
+        all_files = api.list_repo_files(
+            repo_id=repo_id,
+            repo_type=repo_type,
+            token=HF_API_TOKEN
+        )
+        
+        # Ensure folder_path ends with /
+        if folder_path and not folder_path.endswith("/"):
+            folder_path = folder_path + "/"
+        
+        files = []
+        for file_path in all_files:
+            if file_path.startswith(folder_path):
+                relative_path = file_path[len(folder_path):]
+                # Only include files directly in this folder (no subdirectories)
+                if "/" not in relative_path and relative_path:
+                    files.append(relative_path)
+        
+        return sorted(files)
+    
+    except RepositoryNotFoundError:
+        logger.warning(f"Repository {repo_id} not found.")
+        return []
+    except Exception as e:
+        logger.error(f"Error listing files in {repo_id}/{folder_path}: {e}")
+        return []
+
+if __name__ == "__main__":
+   issuer_id = "https://example.edu/issuers/565049"
+   # Example usage
+   public_key, private_key = get_issuer_keypair(issuer_id)
+   print(f"Public Key: {public_key}")
+   print(f"Private Key: {private_key}")
+
+   # Example to store keys
+   store_issuer_keypair(issuer_id, public_key, private_key)
+
+   # Example to list issuer IDs
+   issuer_ids = list_issuer_ids()
+
+   print(f"Issuer IDs: {issuer_ids}")

battlewords/ui.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 from . import __version__ as version
-from typing import Iterable, Tuple, Optional
+from typing import Iterable, Tuple, Optional, Any
 import streamlit as st
 import streamlit.components.v1 as components
 
@@ -20,6 +20,8 @@ from .models import Coord, GameState, Puzzle
 from .word_loader import get_wordlist_files, load_word_list, compute_word_difficulties
 from .ui_helpers import inject_styles, fig_to_pil_rgba, ocean_background_css, inject_ocean_layers, show_spinner, fade_out_spinner, start_root_fade_in, finish_root_fade_in
 from .modules.version_info import versions_html
+from .modules.constants import HF_REPO_ID, HALL_OF_LEGENDS_FILE
+from .modules.storage import _get_json_from_repo, _upload_json_to_repo
 
 # --- Spinner context manager for custom spinner ---
 class CustomSpinner:
@@ -471,6 +473,37 @@ def _render_grid(show_grid_ticks: bool = True):
         unsafe_allow_html=True,
     )
 
+    # Legendary-only Hall of Legends save prompt
+    run_uid = f"{getattr(state.puzzle, 'uid', '')}"
+    if state.score >= 46:
+        st.markdown("### Hall of Legends")
+        st.caption("You reached Legendary. Save this run to the Hall of Legends?")
+
+        if st.button("Save to Hall of Legends", key="save_hall_of_legends"):
+            hall_entry = {
+                "uid": run_uid,
+                "score": int(state.score),
+                "tier": "Legendary",
+                "puzzle_words": [w.text for w in state.puzzle.words],
+                "points_by_word": dict(st.session_state.get("points_by_word", {})),
+                "start_time": (state.start_time.isoformat() if state.start_time else ""),
+                "end_time": (state.end_time.isoformat() if state.end_time else ""),
+                "elapsed_seconds": elapsed_seconds,
+                "game_mode": state.game_mode,
+                "wordlist": st.session_state.get("selected_wordlist", ""),
+                "metadata": {"app_version": version},
+            }
+
+            ok, message = _save_hall_entry(hall_entry)
+            st.session_state["hall_save_message"] = message
+            st.session_state["hall_saved_uid"] = run_uid if ok else ""
+
+        if st.session_state.get("hall_saved_uid") == run_uid:
+            st.success(st.session_state.get("hall_save_message", "Saved to Hall of Legends."))
+            st.markdown("[View Hall of Legends](?page=hall)")
+        elif st.session_state.get("hall_save_message"):
+            st.info(st.session_state.get("hall_save_message"))
+
     grid_container = st.container()
     with grid_container:        
         for r in range(size):
@@ -1174,6 +1207,69 @@ def _render_game_over(state: GameState):
         if visible:
             _game_over_dialog(state)
 
+
+def _normalize_query_value(value: Any) -> str:
+    if isinstance(value, list):
+        return str(value[0]) if value else ""
+    if value is None:
+        return ""
+    return str(value)
+
+
+def _load_hall_entries() -> list[dict[str, Any]]:
+    if not HF_REPO_ID:
+        return []
+    data = _get_json_from_repo(HF_REPO_ID, HALL_OF_LEGENDS_FILE, "dataset")
+    return data if isinstance(data, list) else []
+
+
+def _save_hall_entry(entry: dict[str, Any]) -> tuple[bool, str]:
+    if not HF_REPO_ID:
+        return False, "HF_REPO_ID is not configured."
+
+    entries = _load_hall_entries()
+    uid = str(entry.get("uid", "")).strip()
+
+    if uid and any(str(e.get("uid", "")) == uid for e in entries):
+        return True, "Already saved to Hall of Legends."
+
+    entries.append(entry)
+    entries.sort(key=lambda x: (-int(x.get("score", 0)), int(x.get("elapsed_seconds", 999999))))
+
+    if _upload_json_to_repo(entries, HF_REPO_ID, HALL_OF_LEGENDS_FILE, "dataset"):
+        return True, "Saved to Hall of Legends."
+    return False, "Unable to save to Hall of Legends."
+
+
+def _render_hall_page() -> None:
+    st.title("Hall of Legends")
+    st.caption("Legendary runs only (score 46+) • Local game, HF-backed Hall storage")
+
+    entries = [e for e in _load_hall_entries() if int(e.get("score", 0)) >= 46]
+    entries.sort(key=lambda x: (-int(x.get("score", 0)), int(x.get("elapsed_seconds", 999999))))
+
+    if not entries:
+        st.info("No Hall of Legends entries yet.")
+        return
+
+    table_rows = []
+    for idx, entry in enumerate(entries[:50], 1):
+        table_rows.append(
+            {
+                "Rank": idx,
+                "Score": int(entry.get("score", 0)),
+                "Tier": entry.get("tier", "Legendary"),
+                "Time (s)": int(entry.get("elapsed_seconds", 0)),
+                "Wordlist": entry.get("wordlist", ""),
+                "Saved": entry.get("end_time", ""),
+                "UID": entry.get("uid", ""),
+            }
+        )
+
+    st.dataframe(table_rows, width="stretch", hide_index=True)
+
+    st.markdown("[Return to game](?overlay=0)")
+
 def run_app():
     start_root_fade_in(0.1)
 
@@ -1183,8 +1279,16 @@ def run_app():
     except Exception:
         params = {}
 
+    page = _normalize_query_value(params.get("page"))
+
+    # Hall of Legends page route
+    if page == "hall":
+        _render_hall_page()
+        finish_root_fade_in(0.35)
+        return
+
     # Handle overlay dismissal
-    if params.get("overlay") == "0":
+    if _normalize_query_value(params.get("overlay")) == "0":
         # Clear param and remember to hide overlay this session
         try:
             st.query_params.clear()
@@ -1198,7 +1302,7 @@ def run_app():
         with CustomSpinner(spinner_placeholder, "Initial Load..."):
             st.session_state["initial_page_loaded"] = True
 
-    # Basic branch: challenge mode and shared games are disabled
+    # Basic branch: game page
 
     if st.session_state.get("needs_initialization", True):
         spinner_placeholder = st.empty()

specs/basic.mdx

@@ -41,9 +41,11 @@ This document defines the “basic” version scope for Battlewords on the `basi
 - Any settings-related UI should be omitted/disabled in this branch.
 
 ### Leaderboard
-- The app **does not need** a leaderboard.
-- No local or remote leaderboard storage is required.
-- No UI navigation or pages for leaderboard are required.
+- The app **does not require** a full-featured leaderboard. However, a minimal, local-only "Hall of Legends" view is allowed as a small exception to the "no leaderboard" rule.
+  - The Hall of Legends MUST only store runs that achieve the Legendary tier (score >= 46).
+  - Hall of Legends storage MUST be local-only (no remote sync) and use the JSON Lines schema described in the requirements document.
+  - The Hall of Legends page MUST NOT be linked from the main UI in standard basic builds. It may be accessible via an explicit query parameter for developer inspection only (for example `?page=hall`).
+  - No sidebar, no footer navigation, and no authentication for Hall of Legends.
 
 ### AI generation of wordlists
 - The basic branch does **not** include AI-generated wordlists or HF-model-backed word generation.

specs/requirements.mdx

@@ -70,6 +70,20 @@ This document captures the implementation requirements for the **basic** branch
   - Triggered when all six words are guessed or when all word letters are revealed.
   - Shows a summary with score and tier.
 
+### Hall of Legends (persistent saves)
+- When a player finishes a game with a Legendary score (46 or higher) the app may offer to save the run to the "Hall of Legends".
+- Only games with score >= 46 are eligible to be saved.
+- Hall persistence uses existing HF-backed storage patterns (no new local Hall data file).
+- Hall routing MUST be available in development and production via `?page=hall`.
+- Hall JSON MUST remain compatible with Wrdler leaderboard schema so existing loaders/tools can parse it:
+  - top-level required keys: `challenge_id`, `entry_type`, `game_mode`, `grid_size`, `puzzle_options`, `users`, `created_at`, `version`, `show_incorrect_guesses`, `enable_free_letters`, `wordlist_source`, `game_title`, `max_display_entries`
+  - `entry_type` MUST be `"hall"`
+  - `users[*]` required keys: `uid`, `username`, `word_list`, `score`, `time`, `timestamp`
+  - `users[*].score` MUST be `>= 46` for every Hall entry
+  - `users[*].word_list_difficulty` is optional
+- Hall read behavior: display top runs sorted by score desc then time asc.
+- The basic branch keeps Hall simple: no authentication and no pagination beyond a capped display list.
+
 ### Scoring tiers
 - OK: < 34
 - Good: 34–37
@@ -94,7 +108,6 @@ This document captures the implementation requirements for the **basic** branch
 ## Out of Scope (Basic)
 - Settings page
 - Leaderboards
-- Challenge mode / remote storage (removed)
-- PWA support (removed)
+- Full daily/weekly leaderboard systems (Hall-only scope)
 - Audio
 - Tests

specs/specs.mdx

@@ -52,6 +52,42 @@ Battlewords is inspired by the classic Battleship game, but uses words instead o
 - Custom loading spinner/overlay for transitions
 - No sidebar, no settings page, no leaderboards
 
+## Hall of Legends (Simplified Leaderboard)
+
+- Purpose: a minimal, read-only listing of saved Legendary runs (score >= 46). The Hall of Legends replaces the previous leaderboard concept with a lightweight, local-only view.
+- Accessibility: Hall of Legends MUST be accessible in both development and production via query-param routing using `?page=hall`.
+- Data source: reads and writes the same HF-backed JSON document used for Hall saves (same structure as existing Wrdler leaderboard JSON format).
+- Display fields: rank (by score, then elapsed time), player-run uid, score, tier, puzzle wordlist name, elapsed time, and timestamp. Points-by-word breakdown is optional and shown in an expandable row.
+- Page constraints: no authentication, no pagination (show latest 50 entries), and client-side sorting is allowed.
+- Export: provide a single CSV export button that streams the currently-displayed rows (client-side only).
+
+### Hall of Legends JSON format (compatible)
+
+Hall entries MUST use the same top-level schema as Wrdler leaderboard JSON files for compatibility:
+
+- `challenge_id` (string): Hall group identifier (example: `hall-of-legends/classic-classic-12x12`)
+- `entry_type` (string): MUST be `"hall"`
+- `game_mode` (string)
+- `grid_size` (integer): `12` for Battlewords
+- `puzzle_options` (object): includes `spacer` and `may_overlap`
+- `users` (array): list of saved runs
+  - each user object includes:
+    - `uid` (string)
+    - `username` (string)
+    - `word_list` (array of six words)
+    - `score` (number, MUST be `>= 46`)
+    - `time` (number of seconds)
+    - `timestamp` (ISO-8601 string)
+    - `word_list_difficulty` (number, optional)
+- `created_at` (ISO-8601 string)
+- `version` (string)
+- `show_incorrect_guesses` (boolean)
+- `enable_free_letters` (boolean)
+- `wordlist_source` (string)
+- `game_title` (string)
+- `max_display_entries` (integer)
+
+
 ## Word Lists
 - Local word list files under `battlewords/words/`.
 - Loaded via `battlewords.word_loader.load_word_list()`.