v0.2.20 - Add Challenge Mode v1.0

README.md

@@ -23,7 +23,7 @@ BattleWords is a vocabulary learning game inspired by classic Battleship mechani
 
 ## Features
 
--12x12 grid with six hidden words (2x4-letter,2x5-letter,2x6-letter)
+- 12x12 grid with six hidden words (2x4-letter, 2x5-letter, 2x6-letter)
 - Words placed horizontally or vertically
 - Radar visualization to help locate word boundaries
 - Reveal grid cells and guess words for points
@@ -38,6 +38,11 @@ BattleWords is a vocabulary learning game inspired by classic Battleship mechani
 - **Dockerfile-based deployment supported for Hugging Face Spaces and other container platforms**
 - **Game ends when all words are guessed or all word letters are revealed**
 - **Incorrect guess history with tooltip and optional display (enabled by default)**
+- **Challenge Mode:** Shareable game links with leaderboard, remote storage, and multi-user results
+
+## Challenge Mode & Leaderboard
+
+When playing a shared challenge (via a `game_id` link), the leaderboard displays all submitted results for that challenge. The leaderboard is **sorted by highest score (descending), then by fastest time (ascending)**. This means players with the most points appear at the top, and ties are broken by the shortest completion time.
 
 ## Installation
 1. Clone the repository:
@@ -93,7 +98,9 @@ docker run -p8501:8501 battlewords
  - `generator.py` – word placement logic
  - `logic.py` – game mechanics (reveal, guess, scoring)
  - `ui.py` – Streamlit UI composition
- - `storage.py` – **NEW**: persistent storage and high scores
+ - `game_storage.py` – Hugging Face remote storage integration and challenge sharing
+ - `local_storage.py` – local JSON storage for results and high scores
+ - `storage.py` – (legacy) local storage and high scores
  - `words/wordlist.txt` – candidate words
 - `specs/` – documentation (`specs.md`, `requirements.md`)
 - `tests/` – unit tests
@@ -104,6 +111,7 @@ docker run -p8501:8501 battlewords
 2. After revealing a letter, enter a guess for a word in the text box.
 3. Earn points for correct guesses and bonus points for unrevealed letters.
 4. **The game ends when all six words are found or all word letters are revealed. Your score tier is displayed.**
+5. **To play a shared challenge, use a link with `?game_id=<sid>`. Your result will be added to the challenge leaderboard.**
 
 ## Changelog
 
@@ -111,6 +119,7 @@ docker run -p8501:8501 battlewords
  - Game Sharing: share unique game URLs with friends to challenge them on the same word set.
  - High Scores: local leaderboard tracking top scores by wordlist and game mode.
  - Persistent Storage: all game results saved locally for personal statistics without accounts.
+ - Challenge Mode: remote storage of challenge results, multi-user leaderboard, and shareable links.
 
 -0.2.20 (development)
  - Remote Storage game_id:
@@ -133,7 +142,7 @@ docker run -p8501:8501 battlewords
 - highscores/highscores.json
 
 Note
-- `battlewords/storage.py` remains local-only storage; a separate HF integration wrapper will be added in a later PR to avoid confusion with generic modules
+- `battlewords/storage.py` remains local-only storage; a separate HF integration wrapper is provided as `game_storage.py` for remote challenge mode.
 
 -0.2.19
   - Fix music and sound effect volume issues 
@@ -431,7 +440,9 @@ Happy gaming and sound designing!
  - `generator.py` – word placement logic
  - `logic.py` – game mechanics (reveal, guess, scoring)
  - `ui.py` – Streamlit UI composition
- - `storage.py` – **NEW**: persistent storage and high scores
+ - `game_storage.py` – Hugging Face remote storage integration and challenge sharing
+ - `local_storage.py` – local JSON storage for results and high scores
+ - `storage.py` – (legacy) local storage and high scores
  - `words/wordlist.txt` – candidate words
 - `specs/` – documentation (`specs.md`, `requirements.md`)
 - `tests/` – unit tests

app.py

@@ -1,6 +1,6 @@
 import streamlit as st
 
-from battlewords.ui import run_app
+from battlewords.ui import run_app, _init_session
 
 
 def _new_game() -> None:

battlewords/__init__.py

@@ -1,2 +1,2 @@
-__version__ = "0.2.19"
-__all__ = ["models", "generator", "logic", "ui"]
+__version__ = "0.2.20"
+__all__ = ["models", "generator", "logic", "ui", "game_storage"]

battlewords/assets/audio/effects/incorrect_guess.mp3

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:0e6f7fb1f8e3b4fe3ca958d486ba667a3a05482a88dff16016e058687ffd41a5
-size 49659
+oid sha256:07f70499881c735fc284e9a6b17f0f6d383b35b6e06f0c90aa672597110b916c
+size 23449

battlewords/game_storage.py

@@ -0,0 +1,474 @@
+# file: battlewords/game_storage.py
+"""
+BattleWords-specific storage wrapper for HuggingFace storage operations.
+
+This module provides high-level functions for saving and loading BattleWords games
+using the shared storage module from battlewords.modules.
+"""
+__version__ = "0.1.1"
+
+import json
+import tempfile
+import os
+from datetime import datetime, timezone
+from typing import Dict, Any, List, Optional, Tuple
+import logging
+
+from battlewords.modules import (
+    upload_files_to_repo,
+    gen_full_url,
+    HF_REPO_ID,
+    SHORTENER_JSON_FILE,
+    SPACE_NAME
+)
+from battlewords.modules.storage import _get_json_from_repo
+from battlewords.local_storage import save_json_to_file
+
+# Configure logging
+logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
+logger = logging.getLogger(__name__)
+
+
+def generate_uid() -> str:
+    """
+    Generate a unique identifier for a game.
+
+    Format: YYYYMMDDTHHMMSSZ-RANDOM
+    Example: 20250123T153045Z-A7B9C2
+
+    Returns:
+        str: Unique game identifier
+    """
+    import random
+    import string
+
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    random_suffix = ''.join(random.choices(string.ascii_uppercase + string.digits, k=6))
+    return f"{timestamp}-{random_suffix}"
+
+
+def serialize_game_settings(
+    word_list: List[str],
+    username: str,
+    score: int,
+    time_seconds: int,
+    game_mode: str,
+    grid_size: int = 12,
+    spacer: int = 1,
+    may_overlap: bool = False,
+    wordlist_source: Optional[str] = None,
+    challenge_id: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Serialize game settings into a JSON-compatible dictionary.
+    Creates initial structure with one user's result.
+    Each user has their own uid and word_list.
+
+    Args:
+        word_list: List of words used in THIS user's game
+        username: Player's name
+        score: Final score achieved
+        time_seconds: Time taken to complete (in seconds)
+        game_mode: Game mode ("classic" or "too_easy")
+        grid_size: Grid size (default: 12)
+        spacer: Word spacing configuration (0-2, default: 1)
+        may_overlap: Whether words can overlap (default: False)
+        wordlist_source: Source file name (e.g., "classic.txt")
+        challenge_id: Optional challenge ID (generated if not provided)
+
+    Returns:
+        dict: Serialized game settings with users array
+    """
+    if challenge_id is None:
+        challenge_id = generate_uid()
+
+    # Create user result entry with their own uid and word_list
+    user_result = {
+        "uid": generate_uid(),  # Unique ID for this user's game
+        "username": username,
+        "word_list": word_list,  # Words THIS user played
+        "score": score,
+        "time": time_seconds,
+        "timestamp": datetime.now(timezone.utc).isoformat()
+    }
+
+    settings = {
+        "challenge_id": challenge_id,  # ID for the challenge itself
+        "game_mode": game_mode,
+        "grid_size": grid_size,
+        "puzzle_options": {
+            "spacer": spacer,
+            "may_overlap": may_overlap
+        },
+        "users": [user_result],  # Array of user results
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "version": __version__
+    }
+
+    # Add wordlist_source if provided
+    if wordlist_source:
+        settings["wordlist_source"] = wordlist_source
+
+    return settings
+
+
+def add_user_result_to_game(
+    sid: str,
+    username: str,
+    word_list: List[str],
+    score: int,
+    time_seconds: int,
+    repo_id: Optional[str] = None
+) -> bool:
+    """
+    Add a user's result to an existing shared challenge.
+    Each user gets their own uid and word_list.
+
+    Args:
+        sid: Short ID of the existing challenge
+        username: Player's name
+        word_list: List of words THIS user played
+        score: Score achieved
+        time_seconds: Time taken (seconds)
+        repo_id: HF repository ID (uses HF_REPO_ID from env if None)
+
+    Returns:
+        bool: True if successfully added, False otherwise
+    """
+    if repo_id is None:
+        repo_id = HF_REPO_ID
+
+    logger.info(f"➕ Adding user result to challenge {sid}")
+
+    try:
+        # Load existing game settings
+        settings = load_game_from_sid(sid, repo_id)
+        if not settings:
+            logger.error(f"❌ Challenge not found: {sid}")
+            return False
+
+        # Create new user result with their own uid and word_list
+        user_result = {
+            "uid": generate_uid(),  # Unique ID for this user's game
+            "username": username,
+            "word_list": word_list,  # Words THIS user played
+            "score": score,
+            "time": time_seconds,
+            "timestamp": datetime.now(timezone.utc).isoformat()
+        }
+
+        # Add to users array
+        if "users" not in settings:
+            settings["users"] = []
+        settings["users"].append(user_result)
+
+        logger.info(f"👥 Now {len(settings['users'])} users in game")
+
+        # Get the file path from the sid
+        status, full_url = gen_full_url(
+            short_url=sid,
+            repo_id=repo_id,
+            json_file=SHORTENER_JSON_FILE
+        )
+
+        if status != "success_retrieved_full" or not full_url:
+            logger.error(f"❌ Could not resolve sid: {sid}")
+            return False
+
+        # Extract challenge_id from URL
+        url_parts = full_url.split("/resolve/main/")
+        if len(url_parts) != 2:
+            logger.error(f"❌ Invalid URL format: {full_url}")
+            return False
+
+        file_path = url_parts[1]  # e.g., "games/{challenge_id}/settings.json"
+        challenge_id = file_path.split("/")[1]  # Extract challenge_id
+        folder_name = f"games/{challenge_id}"
+
+        # Save updated settings back to HF
+        try:
+            with tempfile.TemporaryDirectory() as tmpdir:
+                settings_path = save_json_to_file(settings, tmpdir, "settings.json")
+                logger.info(f"📤 Updating {folder_name}/settings.json")
+
+                response = upload_files_to_repo(
+                    files=[settings_path],
+                    repo_id=repo_id,
+                    folder_name=folder_name,
+                    repo_type="dataset"
+                )
+
+            logger.info(f"✅ User result added for {username}")
+            return True
+
+        except Exception as e:
+            logger.error(f"❌ Failed to upload updated settings: {e}")
+            return False
+
+    except Exception as e:
+        logger.error(f"❌ Failed to add user result: {e}")
+        return False
+
+
+def save_game_to_hf(
+    word_list: List[str],
+    username: str,
+    score: int,
+    time_seconds: int,
+    game_mode: str,
+    grid_size: int = 12,
+    spacer: int = 1,
+    may_overlap: bool = False,
+    repo_id: Optional[str] = None,
+    wordlist_source: Optional[str] = None
+) -> Tuple[str, Optional[str], Optional[str]]:
+    """
+    Save game settings to HuggingFace repository and generate shareable URL.
+    Creates a new game entry with the first user's result.
+
+    This function:
+    1. Generates a unique UID for the game
+    2. Serializes game settings to JSON with first user
+    3. Uploads settings.json to HF repo under games/{uid}/
+    4. Creates a shortened URL (sid) for sharing
+    5. Returns the full URL and short ID
+
+    Args:
+        word_list: List of words used in the game
+        username: Player's name
+        score: Final score achieved
+        time_seconds: Time taken to complete (in seconds)
+        game_mode: Game mode ("classic" or "too_easy")
+        grid_size: Grid size (default: 12)
+        spacer: Word spacing configuration (0-2, default: 1)
+        may_overlap: Whether words can overlap (default: False)
+        repo_id: HF repository ID (uses HF_REPO_ID from env if None)
+        wordlist_source: Source wordlist file name (e.g., "classic.txt")
+
+    Returns:
+        tuple: (challenge_id, full_url, sid) where:
+            - challenge_id: Unique challenge identifier
+            - full_url: Full URL to settings.json
+            - sid: Shortened ID for sharing (8 characters)
+
+    Raises:
+        Exception: If upload or URL shortening fails
+
+    Example:
+        >>> uid, full_url, sid = save_game_to_hf(
+        ...     word_list=["WORD", "TEST", "GAME", "PLAY", "SCORE", "FINAL"],
+        ...     username="Alice",
+        ...     score=42,
+        ...     time_seconds=180,
+        ...     game_mode="classic",
+        ...     wordlist_source="classic.txt"
+        ... )
+        >>> print(f"Share: https://{SPACE_NAME}/?game_id={sid}")
+    """
+    if repo_id is None:
+        repo_id = HF_REPO_ID
+
+    logger.info(f"💾 Saving game to HuggingFace repo: {repo_id}")
+
+    # Generate challenge ID and serialize settings
+    challenge_id = generate_uid()
+    settings = serialize_game_settings(
+        word_list=word_list,
+        username=username,
+        score=score,
+        time_seconds=time_seconds,
+        game_mode=game_mode,
+        grid_size=grid_size,
+        spacer=spacer,
+        may_overlap=may_overlap,
+        challenge_id=challenge_id,
+        wordlist_source=wordlist_source
+    )
+
+    logger.debug(f"🆔 Generated Challenge ID: {challenge_id}")
+
+    # Write settings to a temp directory using a fixed filename 'settings.json'
+    folder_name = f"games/{challenge_id}"
+    try:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            settings_path = save_json_to_file(settings, tmpdir, "settings.json")
+            logger.info(f"📤 Uploading to {folder_name}/settings.json")
+            # Upload to HF repo under games/{uid}/settings.json
+            response = upload_files_to_repo(
+                files=[settings_path],
+                repo_id=repo_id,
+                folder_name=folder_name,
+                repo_type="dataset"
+            )
+
+        # Construct full URL to settings.json
+        full_url = f"https://huggingface.co/datasets/{repo_id}/resolve/main/{folder_name}/settings.json"
+        logger.info(f"✅ Uploaded: {full_url}")
+
+        # Generate short URL
+        logger.info("🔗 Creating short URL...")
+        status, sid = gen_full_url(
+            full_url=full_url,
+            repo_id=repo_id,
+            json_file=SHORTENER_JSON_FILE
+        )
+
+        if status in ["created_short", "success_retrieved_short", "exists_match"]:
+            logger.info(f"✅ Short ID created: {sid}")
+            share_url = f"https://{SPACE_NAME}/?game_id={sid}"
+            logger.info(f"🎮 Share URL: {share_url}")
+            return challenge_id, full_url, sid
+        else:
+            logger.warning(f"⚠️ URL shortening failed: {status}")
+            return challenge_id, full_url, None
+
+    except Exception as e:
+        logger.error(f"❌ Failed to save game: {e}")
+        raise
+
+
+def load_game_from_sid(
+    sid: str,
+    repo_id: Optional[str] = None
+) -> Optional[Dict[str, Any]]:
+    """
+    Load game settings from a short ID (sid).
+    If settings.json cannot be found, return None and allow normal game loading.
+
+    Args:
+        sid: Short ID (8 characters) from shareable URL
+        repo_id: HF repository ID (uses HF_REPO_ID from env if None)
+
+    Returns:
+        dict | None: Game settings or None if not found
+
+        dict: Challenge settings containing:
+            - challenge_id: Unique challenge identifier
+            - wordlist_source: Source wordlist file (e.g., "classic.txt")
+            - game_mode: Game mode
+            - grid_size: Grid size
+            - puzzle_options: Puzzle configuration (spacer, may_overlap)
+            - users: Array of user results, each with:
+                - uid: Unique user game identifier
+                - username: Player name
+                - word_list: Words THIS user played
+                - score: Score achieved
+                - time: Time taken (seconds)
+                - timestamp: When result was recorded
+            - created_at: When challenge was created
+            - version: Storage version
+
+        Returns None if sid not found or download fails
+
+    Example:
+        >>> settings = load_game_from_sid("abc12345")
+        >>> if settings:
+        ...     print(f"Challenge ID: {settings['challenge_id']}")
+        ...     print(f"Wordlist: {settings['wordlist_source']}")
+        ...     for user in settings['users']:
+        ...         print(f"{user['username']}: {user['score']} pts")
+    """
+    if repo_id is None:
+        repo_id = HF_REPO_ID
+
+    logger.info(f"🔍 Loading game from sid: {sid}")
+
+    try:
+        # Resolve sid to full URL
+        status, full_url = gen_full_url(
+            short_url=sid,
+            repo_id=repo_id,
+            json_file=SHORTENER_JSON_FILE
+        )
+
+        if status != "success_retrieved_full" or not full_url:
+            logger.warning(f"⚠️ Could not resolve sid: {sid} (status: {status})")
+            return None
+
+        logger.info(f"✅ Resolved to: {full_url}")
+
+        # Extract the file path from the full URL
+        # URL format: https://huggingface.co/datasets/{repo_id}/resolve/main/{path}
+        # We need just the path part: games/{uid}/settings.json
+        try:
+            url_parts = full_url.split("/resolve/main/")
+            if len(url_parts) != 2:
+                logger.error(f"❌ Invalid URL format: {full_url}")
+                return None
+            
+            file_path = url_parts[1]
+            logger.info(f"📥 Downloading {file_path} using authenticated API...")
+            
+            settings = _get_json_from_repo(repo_id, file_path, repo_type="dataset")
+            if not settings:
+                logger.error(f"❌ settings.json not found for sid: {sid}. Loading normal game.")
+                return None
+            
+            logger.info(f"✅ Loaded challenge: {settings.get('challenge_id', 'unknown')}")
+            users = settings.get('users', [])
+            logger.debug(f"Users in challenge: {len(users)}")
+
+            return settings
+
+        except Exception as e:
+            logger.error(f"❌ Failed to parse URL or download: {e}")
+            return None
+
+    except Exception as e:
+        logger.error(f"❌ Unexpected error loading game: {e}")
+        return None
+
+
+def get_shareable_url(sid: str) -> str:
+    """
+    Generate a shareable URL from a short ID.
+
+    Args:
+        sid: Short ID (8 characters)
+
+    Returns:
+        str: Full shareable URL
+
+    Example:
+        >>> url = get_shareable_url("abc12345")
+        >>> print(url)
+        https://Surn/BattleWords/?game_id=abc12345
+    """
+    return f"https://{SPACE_NAME}/?game_id={sid}"
+
+
+if __name__ == "__main__":
+    # Example usage
+    print("BattleWords Game Storage Module")
+    print(f"Version: {__version__}")
+    print(f"Target Repository: {HF_REPO_ID}")
+    print(f"Space Name: {SPACE_NAME}")
+
+    # Example: Save a game
+    print("\n--- Example: Save Game ---")
+    try:
+        challenge_id, full_url, sid = save_game_to_hf(
+            word_list=["WORD", "TEST", "GAME", "PLAY", "SCORE", "FINAL"],
+            username="Alice",
+            score=42,
+            time_seconds=180,
+            game_mode="classic"
+        )
+        print(f"Challenge ID: {challenge_id}")
+        print(f"Full URL: {full_url}")
+        print(f"Short ID: {sid}")
+        print(f"Share: {get_shareable_url(sid)}")
+    except Exception as e:
+        print(f"Error: {e}")
+
+    # Example: Load a game
+    print("\n--- Example: Load Game ---")
+    if sid:
+        settings = load_game_from_sid(sid)
+        if settings:
+            print(f"Loaded Challenge: {settings['challenge_id']}")
+            print(f"Wordlist Source: {settings.get('wordlist_source', 'N/A')}")
+            users = settings.get('users', [])
+            print(f"Users: {len(users)}")
+            for user in users:
+                print(f"  - {user['username']}: {user['score']} pts in {user['time']}s")

battlewords/generator.py

@@ -39,6 +39,8 @@ def generate_puzzle(
     spacer: int = 1,
     puzzle_id: Optional[str] = None,  # NEW
     _retry: int = 0,  # NEW internal for deterministic retries
+    target_words: Optional[List[str]] = None,  # NEW: for loading shared games
+    may_overlap: bool = False,  # NEW: for future crossword-style gameplay
 ) -> Puzzle:
     """
     Place exactly six words: 2x4, 2x5, 2x6, horizontal or vertical,
@@ -54,6 +56,8 @@ def generate_puzzle(
       - 0: words may touch
       - 1: at least 1 blank tile between words (default)
       - 2: at least 2 blank tiles between words
+    - target_words: optional list of exactly 6 words to use (for shared games)
+    - may_overlap: whether words can overlap (default False, for future use)
 
     Determinism:
     - If puzzle_id is provided, it's used to derive the RNG seed. Retries use f"{puzzle_id}:{_retry}".
@@ -71,20 +75,34 @@ def generate_puzzle(
         seed_val = None
 
     rng = random.Random(seed_val) if seed_val is not None else random.Random()
-    words_by_len = words_by_len or load_word_list()
-    target_lengths = [4, 4, 5, 5, 6, 6]
+
+    # If target_words is provided, use those specific words
+    if target_words:
+        if len(target_words) != 6:
+            raise ValueError(f"target_words must contain exactly 6 words, got {len(target_words)}")
+        # Group target words by length
+        pools: Dict[int, List[str]] = {}
+        for word in target_words:
+            L = len(word)
+            if L not in pools:
+                pools[L] = []
+            pools[L].append(word.upper())
+        target_lengths = sorted([len(w) for w in target_words])
+    else:
+        # Normal random word selection
+        words_by_len = words_by_len or load_word_list()
+        target_lengths = [4, 4, 5, 5, 6, 6]
+        # Pre-shuffle the word pools for variety but deterministic with seed.
+        pools: Dict[int, List[str]] = {}
+        for L in (4, 5, 6):
+            unique_words = list(dict.fromkeys(words_by_len.get(L, [])))
+            rng.shuffle(unique_words)
+            pools[L] = unique_words
 
     used: set[Coord] = set()
     used_texts: set[str] = set()
     placed: List[Word] = []
 
-    # Pre-shuffle the word pools for variety but deterministic with seed.
-    pools: Dict[int, List[str]] = {}
-    for L in (4, 5, 6):
-        unique_words = list(dict.fromkeys(words_by_len.get(L, [])))
-        rng.shuffle(unique_words)
-        pools[L] = unique_words
-
     attempts = 0
     for L in target_lengths:
         placed_ok = False
@@ -140,7 +158,7 @@ def generate_puzzle(
                 spacer=spacer,
             )
 
-    puzzle = Puzzle(words=placed, spacer=spacer)
+    puzzle = Puzzle(words=placed, spacer=spacer, may_overlap=may_overlap)
     try:
         validate_puzzle(puzzle, grid_size=grid_size)
     except AssertionError:

battlewords/{storage.py → local_storage.py}

@@ -1,4 +1,4 @@
-# file: battlewords/storage.py
+# file: battlewords/local_storage.py
 """
 Storage module for BattleWords game.
 
@@ -161,6 +161,17 @@ class GameStorage:
             "fastest_time": min(r.elapsed_seconds for r in player_results)
         }
 
+def save_json_to_file(data: dict, directory: str, filename: str = "settings.json") -> str:
+    """
+    Save a dictionary as a JSON file with a specified filename in the given directory.
+    Returns the full path to the saved file.
+    """
+    os.makedirs(directory, exist_ok=True)
+    file_path = os.path.join(directory, filename)
+    with open(file_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+    return file_path
+
 def generate_game_id_from_words(words: List[str]) -> str:
     import hashlib
     sorted_words = sorted([w.upper() for w in words])

battlewords/modules/__init__.py

@@ -0,0 +1,80 @@
+# battlewords/modules/__init__.py
+"""
+Shared utility modules for BattleWords.
+
+These modules are imported from the OpenBadge project and provide
+reusable functionality for storage, constants, and file utilities.
+"""
+
+from .storage import (
+    upload_files_to_repo,
+    gen_full_url,
+    generate_permalink,
+    generate_permalink_from_urls,
+    store_issuer_keypair,
+    get_issuer_keypair,
+    get_verification_methods_registry,
+    list_issuer_ids
+)
+
+from .constants import (
+    HF_API_TOKEN,
+    HF_REPO_ID,
+    SHORTENER_JSON_FILE,
+    SPACE_NAME,
+    TMPDIR,
+    upload_file_types,
+    model_extensions,
+    image_extensions,
+    audio_extensions,
+    video_extensions,
+    doc_extensions
+)
+
+from .file_utils import (
+    get_file_parts,
+    rename_file_to_lowercase_extension,
+    get_filename,
+    convert_title_to_filename,
+    get_filename_from_filepath,
+    delete_file,
+    get_unique_file_path,
+    download_and_save_image,
+    download_and_save_file
+)
+
+__all__ = [
+    # storage.py
+    'upload_files_to_repo',
+    'gen_full_url',
+    'generate_permalink',
+    'generate_permalink_from_urls',
+    'store_issuer_keypair',
+    'get_issuer_keypair',
+    'get_verification_methods_registry',
+    'list_issuer_ids',
+
+    # constants.py
+    'HF_API_TOKEN',
+    'HF_REPO_ID',
+    'SHORTENER_JSON_FILE',
+    'SPACE_NAME',
+    'TMPDIR',
+    'upload_file_types',
+    'model_extensions',
+    'image_extensions',
+    'audio_extensions',
+    'video_extensions',
+    'doc_extensions',
+
+    # file_utils.py
+    'get_file_parts',
+    'rename_file_to_lowercase_extension',
+    'get_filename',
+    'convert_title_to_filename',
+    'get_filename_from_filepath',
+    'delete_file',
+    'get_unique_file_path',
+    'download_and_save_image',
+    'download_and_save_file'
+]

battlewords/modules/constants.py

@@ -0,0 +1,60 @@
+# battlewords/modules/constants.py
+"""
+Storage-related constants for BattleWords.
+Trimmed version of OpenBadge constants - only includes what's needed for storage.py
+"""
+import os
+import tempfile
+import logging
+from pathlib import Path
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+dotenv_path = Path(__file__).parent.parent.parent / '.env'
+load_dotenv(dotenv_path)
+
+# Hugging Face Configuration
+HF_API_TOKEN = os.getenv("HF_TOKEN", os.getenv("HF_API_TOKEN", None))
+CRYPTO_PK = os.getenv("CRYPTO_PK", None)
+
+# Repository Configuration
+HF_REPO_ID = os.getenv("HF_REPO_ID", "Surn/Storage")
+SPACE_NAME = os.getenv('SPACE_NAME', 'Surn/BattleWords')
+SHORTENER_JSON_FILE = "shortener.json"
+
+# Temporary Directory Configuration
+try:
+    if os.environ.get('TMPDIR'):
+        TMPDIR = os.environ['TMPDIR']
+    else:
+        TMPDIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'tmp')
+except:
+    TMPDIR = tempfile.gettempdir()
+
+os.makedirs(TMPDIR, exist_ok=True)
+
+# File Extension Sets (for storage.py compatibility)
+model_extensions = {".glb", ".gltf", ".obj", ".ply"}
+model_extensions_list = list(model_extensions)
+
+image_extensions = {".png", ".jpg", ".jpeg", ".webp"}
+image_extensions_list = list(image_extensions)
+
+audio_extensions = {".mp3", ".wav", ".ogg", ".flac"}
+audio_extensions_list = list(audio_extensions)
+
+video_extensions = {".mp4"}
+video_extensions_list = list(video_extensions)
+
+doc_extensions = {".json"}
+doc_extensions_list = list(doc_extensions)
+
+upload_file_types = (
+    model_extensions_list +
+    image_extensions_list +
+    audio_extensions_list +
+    video_extensions_list +
+    doc_extensions_list
+)
+
+logging.getLogger("matplotlib").setLevel(logging.WARNING)

battlewords/modules/file_utils.py

@@ -0,0 +1,204 @@
+# file_utils
+import os
+import shutil
+from pathlib import Path
+import requests
+from PIL import Image
+from io import BytesIO
+from urllib.parse import urlparse
+
+def get_file_parts(file_path: str):
+    # Split the path into directory and filename
+    directory, filename = os.path.split(file_path)
+    
+    # Split the filename into name and extension
+    name, ext = os.path.splitext(filename)
+    
+    # Convert the extension to lowercase
+    new_ext = ext.lower()
+    return directory, filename, name, ext, new_ext
+
+def rename_file_to_lowercase_extension(file_path: str) -> str:
+    """
+    Renames a file's extension to lowercase in place.
+
+    Parameters:
+        file_path (str): The original file path.
+
+    Returns:
+        str: The new file path with the lowercase extension.
+
+    Raises:
+        OSError: If there is an error renaming the file (e.g., file not found, permissions issue).
+    """
+    directory, filename, name, ext, new_ext = get_file_parts(file_path)
+    # If the extension changes, rename the file
+    if ext != new_ext:
+        new_filename = name + new_ext
+        new_file_path = os.path.join(directory, new_filename)
+        try:
+            os.rename(file_path, new_file_path)
+            print(f"Rename {file_path} to {new_file_path}\n")
+        except Exception as e:
+            print(f"os.rename failed: {e}. Falling back to binary copy operation.")
+            try:
+                # Read the file in binary mode and write it to new_file_path
+                with open(file_path, 'rb') as f:
+                    data = f.read()
+                with open(new_file_path, 'wb') as f:
+                    f.write(data)
+                    print(f"Copied {file_path} to {new_file_path}\n")
+                # Optionally, remove the original file after copying
+                #os.remove(file_path)
+            except Exception as inner_e:
+                print(f"Failed to copy file from {file_path} to {new_file_path}: {inner_e}")
+                raise inner_e
+        return new_file_path
+    else:
+        return file_path
+
+def get_filename(file):
+    # extract filename from file object
+    filename = None
+    if file is not None:
+        filename = file.name
+    return filename
+
+def convert_title_to_filename(title):
+    # convert title to filename
+    filename = title.lower().replace(" ", "_").replace("/", "_")
+    return filename
+
+def get_filename_from_filepath(filepath):
+    file_name = os.path.basename(filepath)
+    file_base, file_extension = os.path.splitext(file_name)
+    return file_base, file_extension
+
+def delete_file(file_path: str) -> None:
+    """
+    Deletes the specified file.
+
+    Parameters:
+        file_path (str): The path to thefile to delete.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        Exception: If there is an error deleting the file.
+    """
+    try:
+        path = Path(file_path)
+        path.unlink()
+        print(f"Deleted original file: {file_path}")
+    except FileNotFoundError:
+        print(f"File not found: {file_path}")
+    except Exception as e:
+        print(f"Error deleting file: {e}")
+
+def get_unique_file_path(directory, filename, file_ext, counter=0):
+    """
+    Recursively increments the filename until a unique path is found.
+    
+    Parameters:
+        directory (str): The directory for the file.
+        filename (str): The base filename.
+        file_ext (str): The file extension including the leading dot.
+        counter (int): The current counter value to append.
+        
+    Returns:
+        str: A unique file path that does not exist.
+    """
+    if counter == 0:
+        filepath = os.path.join(directory, f"{filename}{file_ext}")
+    else:
+        filepath = os.path.join(directory, f"{filename}{counter}{file_ext}")
+
+    if not os.path.exists(filepath):
+        return filepath
+    else:
+        return get_unique_file_path(directory, filename, file_ext, counter + 1)
+
+# Example usage:
+# new_file_path = get_unique_file_path(video_dir, title_file_name, video_new_ext)
+
+def download_and_save_image(url: str, dst_folder: Path, token: str = None) -> Path:
+    """
+    Downloads an image from a URL with authentication if a token is provided,
+    verifies it with PIL, and saves it in dst_folder with a unique filename.
+
+    Args:
+        url (str): The image URL.
+        dst_folder (Path): The destination folder for the image.
+        token (str, optional): A valid Bearer token. If not provided, the HF_API_TOKEN
+                              environment variable is used if available.
+
+    Returns:
+        Path: The saved image's file path.
+    """
+    headers = {}
+    # Use provided token; otherwise, fall back to environment variable.
+    api_token = token
+    if api_token:
+        headers["Authorization"] = f"Bearer {api_token}"
+    
+    response = requests.get(url, headers=headers)
+    response.raise_for_status()
+    pil_image = Image.open(BytesIO(response.content))
+    
+    parsed_url = urlparse(url)
+    original_filename = os.path.basename(parsed_url.path)  # e.g., "background.png"
+    base, ext = os.path.splitext(original_filename)
+    
+    # Use get_unique_file_path from file_utils.py to generate a unique file path.
+    unique_filepath_str = get_unique_file_path(str(dst_folder), base, ext)
+    dst = Path(unique_filepath_str)
+    dst_folder.mkdir(parents=True, exist_ok=True)
+    pil_image.save(dst)
+    return dst
+
+def download_and_save_file(url: str, dst_folder: Path, token: str = None) -> Path:
+    """
+    Downloads a binary file (e.g., audio or video) from a URL with authentication if a token is provided,
+    and saves it in dst_folder with a unique filename.
+
+    Args:
+        url (str): The file URL.
+        dst_folder (Path): The destination folder for the file.
+        token (str, optional): A valid Bearer token.
+
+    Returns:
+        Path: The saved file's path.
+    """
+    headers = {}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    
+    response = requests.get(url, headers=headers)
+    response.raise_for_status()
+    
+    parsed_url = urlparse(url)
+    original_filename = os.path.basename(parsed_url.path)
+    base, ext = os.path.splitext(original_filename)
+    
+    unique_filepath_str = get_unique_file_path(str(dst_folder), base, ext)
+    dst = Path(unique_filepath_str)
+    dst_folder.mkdir(parents=True, exist_ok=True)
+    
+    with open(dst, "wb") as f:
+        f.write(response.content)
+    
+    return dst
+
+
+if __name__ == "__main__":
+    # Example usage
+    url = "https://example.com/image.png"
+    dst_folder = Path("downloads")
+    download_and_save_image(url, dst_folder)
+    # Example usage for file download
+    file_url = "https://example.com/file.mp3"
+    downloaded_file = download_and_save_file(file_url, dst_folder)
+    print(f"File downloaded to: {downloaded_file}")
+    # Example usage for renaming file extension
+    file_path = "example.TXT"
+    new_file_path = rename_file_to_lowercase_extension(file_path)
+    print(f"Renamed file to: {new_file_path}")

battlewords/modules/storage.md

@@ -0,0 +1,227 @@
+# 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.
+- **🔑 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)
+## 🔑 Cryptographic Key Management Functions
+
+### 5. `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")
+### 6. `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")
+### 7. `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("---")
+### 8. `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, 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,708 @@
+# modules/storage.py
+__version__ = "0.1.5"
+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 []
+
+
+    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

@@ -27,6 +27,7 @@ from .audio import (
     _inject_audio_control_sync,
     play_sound_effect,
 )
+from .game_storage import load_game_from_sid, save_game_to_hf, get_shareable_url, add_user_result_to_game
 
 st.set_page_config(initial_sidebar_state="collapsed")
 
@@ -363,6 +364,9 @@ def _init_session() -> None:
         return
     # --- Preserve music settings ---
 
+    # Check if we're loading a shared game
+    shared_settings = st.session_state.get("shared_game_settings")
+
     # Ensure a default selection exists before creating the puzzle
     files = get_wordlist_files()
     if "selected_wordlist" not in st.session_state and files:
@@ -370,8 +374,34 @@ def _init_session() -> None:
     if "game_mode" not in st.session_state:
         st.session_state.game_mode = "classic"
 
-    words = load_word_list(st.session_state.get("selected_wordlist"))
-    puzzle = generate_puzzle(grid_size=12, words_by_len=words)
+    # Generate puzzle with shared game settings if available
+    if shared_settings:
+        # Each user gets different random words from the same wordlist source
+        wordlist_source = shared_settings.get("wordlist_source", "classic.txt")
+        spacer = shared_settings["puzzle_options"].get("spacer", 1)
+        may_overlap = shared_settings["puzzle_options"].get("may_overlap", False)
+        game_mode = shared_settings.get("game_mode", "classic")
+
+        # Override selected wordlist to match challenge
+        st.session_state.selected_wordlist = wordlist_source
+
+        # Generate puzzle with random words from the challenge's wordlist
+        words = load_word_list(wordlist_source)
+        puzzle = generate_puzzle(
+            grid_size=12,
+            words_by_len=words,
+            spacer=spacer,
+            may_overlap=may_overlap
+        )
+        st.session_state.game_mode = game_mode
+        st.session_state.spacer = spacer
+
+        # Users will see leaderboard showing all players' results
+        # Each player has their own uid and word_list in the users array
+    else:
+        # Normal game generation
+        words = load_word_list(st.session_state.get("selected_wordlist"))
+        puzzle = generate_puzzle(grid_size=12, words_by_len=words)
 
     st.session_state.puzzle = puzzle
     st.session_state.grid_size = 12
@@ -459,6 +489,76 @@ def _sync_back(state: GameState) -> None:
 
 def _render_header():
     st.title(f"Battlewords v{version}")
+
+    # Show Challenge Mode banner if loading a shared game
+    shared_settings = st.session_state.get("shared_game_settings")
+    if shared_settings:
+        users = shared_settings.get("users", [])
+
+        if users:
+            # Sort users by score (descending), then by time (ascending)
+            sorted_users = sorted(users, key=lambda u: (-u["score"], u["time"]))
+            best_user = sorted_users[0]
+            best_score = best_user["score"]
+            best_time = best_user["time"]
+            mins, secs = divmod(best_time, 60)
+            best_time_str = f"{mins:02d}:{secs:02d}"
+
+            # Build leaderboard HTML
+            leaderboard_rows = []
+            for i, user in enumerate(sorted_users[:5], 1):  # Top 5
+                u_mins, u_secs = divmod(user["time"], 60)
+                u_time_str = f"{u_mins:02d}:{u_secs:02d}"
+                medal = ["🥇", "🥈", "🥉"][i-1] if i <= 3 else f"{i}."
+                leaderboard_rows.append(
+                    f"<div style='padding:0.25rem; font-size:0.85rem;'>{medal} {user['username']}: {user['score']} pts in {u_time_str}</div>"
+                )
+            leaderboard_html = "".join(leaderboard_rows)
+
+            st.markdown(
+                f"""
+                <div style="
+                    background: linear-gradient(90deg, #1d64c8 0%, #165ba8 100%);
+                    color: white;
+                    padding: 1rem;
+                    border-radius: 0.5rem;
+                    margin-bottom: 1rem;
+                    text-align: center;
+                    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+                ">
+                    🎯 <strong>CHALLENGE MODE</strong> 🎯<br/>
+                    <span style="font-size: 0.9rem;">
+                        Beat the best: <strong>{best_score} points</strong> in <strong>{best_time_str}</strong> by <strong>{best_user['username']}</strong>
+                    </span>
+                    <div style="margin-top:0.75rem; border-top: 1px solid rgba(255,255,255,0.3); padding-top:0.5rem;">
+                        <strong style="font-size:0.9rem;">🏆 Leaderboard</strong>
+                        {leaderboard_html}
+                    </div>
+                </div>
+                """,
+                unsafe_allow_html=True
+            )
+        else:
+            st.markdown(
+                """
+                <div style="
+                    background: linear-gradient(90deg, #1d64c8 0%, #165ba8 100%);
+                    color: white;
+                    padding: 1rem;
+                    border-radius: 0.5rem;
+                    margin-bottom: 1rem;
+                    text-align: center;
+                    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+                ">
+                    🎯 <strong>CHALLENGE MODE</strong> 🎯<br/>
+                    <span style="font-size: 0.9rem;">
+                        Be the first to complete this challenge!
+                    </span>
+                </div>
+                """,
+                unsafe_allow_html=True
+            )
+
     st.subheader("Reveal letters in cells, then guess the words!")
     # st.markdown(
     #     "- Grid is 12×12 with 6 words (two 4-letter, two 5-letter, two 6-letter).\n"
@@ -1372,6 +1472,120 @@ def _game_over_content(state: GameState) -> None:
         height=0,
     )
 
+    # Share Challenge Button
+    st.markdown("---")
+    st.markdown("### 🎮 Share Your Challenge")
+
+    # Check if this is a shared game being completed
+    is_shared_game = st.session_state.get("loaded_game_sid") is not None
+    existing_sid = st.session_state.get("loaded_game_sid")
+
+    # Username input
+    if "player_username" not in st.session_state:
+        st.session_state["player_username"] = ""
+
+    username = st.text_input(
+        "Enter your name (optional)",
+        value=st.session_state.get("player_username", ""),
+        key="username_input",
+        placeholder="Anonymous"
+    )
+    if username:
+        st.session_state["player_username"] = username
+    else:
+        username = "Anonymous"
+
+    # Check if share URL already generated
+    if "share_url" not in st.session_state or st.session_state.get("share_url") is None:
+        button_text = "📊 Submit Your Result" if is_shared_game else "🔗 Generate Share Link"
+
+        if st.button(button_text, key="generate_share_link", use_container_width=True):
+            try:
+                # Extract game data
+                word_list = [w.text for w in state.puzzle.words]
+                spacer = state.puzzle.spacer
+                may_overlap = state.puzzle.may_overlap
+                wordlist_source = st.session_state.get("selected_wordlist", "unknown")
+
+                if is_shared_game and existing_sid:
+                    # Add result to existing game
+                    success = add_user_result_to_game(
+                        sid=existing_sid,
+                        username=username,
+                        word_list=word_list,  # Each user gets different words
+                        score=state.score,
+                        time_seconds=elapsed_seconds
+                    )
+
+                    if success:
+                        share_url = get_shareable_url(existing_sid)
+                        st.session_state["share_url"] = share_url
+                        st.session_state["share_sid"] = existing_sid
+                        st.success(f"✅ Result submitted for {username}!")
+                        st.rerun()
+                    else:
+                        st.error("Failed to submit result")
+                else:
+                    # Create new game
+                    challenge_id, full_url, sid = save_game_to_hf(
+                        word_list=word_list,
+                        username=username,
+                        score=state.score,
+                        time_seconds=elapsed_seconds,
+                        game_mode=state.game_mode,
+                        grid_size=state.grid_size,
+                        spacer=spacer,
+                        may_overlap=may_overlap,
+                        wordlist_source=wordlist_source
+                    )
+
+                    if sid:
+                        share_url = get_shareable_url(sid)
+                        st.session_state["share_url"] = share_url
+                        st.session_state["share_sid"] = sid
+                        st.rerun()
+                    else:
+                        st.error("Failed to generate short URL")
+
+            except Exception as e:
+                st.error(f"Failed to save game: {e}")
+    else:
+        # Display generated share URL
+        share_url = st.session_state["share_url"]
+        st.success("✅ Share link generated!")
+        st.code(share_url, language=None)
+
+        # Copy to clipboard button
+        components.html(
+            f"""
+            <script>
+            function copyToClipboard() {{
+                navigator.clipboard.writeText("{share_url}").then(function() {{
+                    alert("Share link copied to clipboard!");
+                }}, function(err) {{
+                    console.error('Could not copy text: ', err);
+                }});
+            }}
+            </script>
+            <button onclick="copyToClipboard()" style="
+                width: 100%;
+                padding: 0.5rem 1rem;
+                background: #1d64c8;
+                color: white;
+                border: none;
+                border-radius: 0.5rem;
+                cursor: pointer;
+                font-size: 1rem;
+                font-weight: bold;
+            ">
+                📋 Copy Link
+            </button>
+            """,
+            height=60
+        )
+
+    st.markdown("---")
+
     # Dialog actions
     if st.button("Close", key="close_game_over"):
         st.session_state["show_gameover_overlay"] = False
@@ -1428,11 +1642,13 @@ def _render_game_over(state: GameState):
             _mount_background_audio(False, None, 0.0)
 
 def run_app():
-    # Handle overlay dismissal via query params using new API
+    # Handle query params using new API
     try:
         params = st.query_params
     except Exception:
         params = {}
+
+    # Handle overlay dismissal
     if params.get("overlay") == "0":
         # Clear param and remember to hide overlay this session
         try:
@@ -1441,6 +1657,32 @@ def run_app():
             pass
         st.session_state["hide_gameover_overlay"] = True
 
+    # Handle game_id for loading shared games
+    if "game_id" in params and "shared_game_loaded" not in st.session_state:
+        sid = params.get("game_id")
+        try:
+            settings = load_game_from_sid(sid)
+            if settings:
+                # Store loaded settings and sid for initialization
+                st.session_state["shared_game_settings"] = settings
+                st.session_state["loaded_game_sid"] = sid  # Store sid for adding results later
+                st.session_state["shared_game_loaded"] = True
+
+                # Get best score and time from users array
+                users = settings.get("users", [])
+                if users:
+                    best_score = max(u["score"] for u in users)
+                    best_time = min(u["time"] for u in users)
+                    st.info(f"🎯 Loading shared challenge (Best: {best_score} pts in {best_time}s by {len(users)} player(s))")
+                else:
+                    st.info(f"🎯 Loading shared challenge")
+            else:
+                st.warning(f"No shared game found for ID: {sid}. Starting a normal game.")
+                st.session_state["shared_game_loaded"] = True  # Prevent repeated attempts
+        except Exception as e:
+            st.error(f"❌ Error loading shared game: {e}")
+            st.session_state["shared_game_loaded"] = True  # Prevent repeated attempts
+
     _init_session()
     st.markdown(ocean_background_css, unsafe_allow_html=True)
     inject_ocean_layers()  # <-- add the animated layers

claude.md

@@ -52,8 +52,14 @@ battlewords/
 │   ├── audio.py             # Background music system
 │   ├── sounds.py            # Sound effects management
 │   ├── generate_sounds.py   # Sound generation utilities
-│   ├── storage.py           # Storage module (v0.3.0 - IN DEVELOPMENT)
+│   ├── game_storage.py      # HF game storage wrapper (v0.1.0)
 │   ├── version_info.py      # Version display
+│   ├── modules/             # Shared utility modules (from OpenBadge)
+│   │   ├── __init__.py      # Module exports
+│   │   ├── storage.py       # HuggingFace storage & URL shortener (v0.1.5)
+│   │   ├── storage.md       # Storage module documentation
+│   │   ├── constants.py     # Storage-related constants (trimmed)
+│   │   └── file_utils.py    # File utility functions
 │   └── words/               # Word list files
 │       ├── classic.txt      # Default word list
 │       ├── fourth_grade.txt # Elementary word list
@@ -154,9 +160,29 @@ battlewords/
   - Maintains 2% margin for tick visibility while ensuring consistent layer alignment
 
 **In Progress (v0.3.0 on cc-01):**
-- Storage module implementation (storage.py created)
-- Game ID system for sharing
-- High score tracking infrastructure
+- ✅ Imported storage modules from OpenBadge project:
+  - `battlewords/modules/storage.py` (v0.1.5) - HuggingFace storage & URL shortener
+  - `battlewords/modules/constants.py` (trimmed) - Storage-related constants
+  - `battlewords/modules/file_utils.py` - File utility functions
+  - `battlewords/modules/storage.md` - Documentation
+- ✅ Created `battlewords/game_storage.py` (v0.1.0) - BattleWords storage wrapper:
+  - `save_game_to_hf()` - Save game to HF repo and generate short URL
+  - `load_game_from_sid()` - Load game from short ID
+  - `generate_uid()` - Generate unique game identifiers
+  - `serialize_game_settings()` - Convert game data to JSON
+  - `get_shareable_url()` - Generate shareable URLs
+- ✅ UI integration complete (`battlewords/ui.py`):
+  - Query parameter parsing for `?game_id=<sid>` on app load
+  - Load shared game settings into session state
+  - Challenge Mode banner showing target score and time
+  - Share button in game over dialog with "Generate Share Link"
+  - Copy-to-clipboard functionality for share URLs
+  - Automatic save to HuggingFace on game completion
+- ✅ Generator updates (`battlewords/generator.py`):
+  - Added `target_words` parameter for loading specific words
+  - Added `may_overlap` parameter (for future crossword mode)
+  - Support for shared game replay with same words, different positions
+- ⏳ High score tracking infrastructure (backend ready, UI pending)
 
 ## Data Models
 
@@ -402,3 +428,10 @@ This file (CLAUDE.md) serves as a **living context document** for AI-assisted de
 
 **Synchronization:**
 Changes to game mechanics should update specs.md → requirements.md → CLAUDE.md → README.md in that order
+
+## Challenge Mode & Remote Storage
+
+- The app supports a Challenge Mode where games can be shared via a short link (`?game_id=<sid>`).
+- Results are stored in a Hugging Face dataset repo using `game_storage.py`.
+- The leaderboard for a challenge is sorted by highest score (descending), then by fastest time (ascending).
+- Each user result is appended to the challenge's `users` array in the remote JSON.

requirements.txt

@@ -1,5 +1,7 @@
 altair
 pandas
+typing
+pathlib
 streamlit
 matplotlib
 numpy
@@ -9,4 +11,5 @@ flake8
 mypy
 requests
 huggingface_hub
-python-dotenv
+python-dotenv
+google-api-core

specs/requirements.md

@@ -247,3 +247,11 @@ E) Acceptance
 F) Implementation Notes
 - Do not replace `battlewords/storage.py` now; introduce a separate integration wrapper (e.g., `battlewords/hf_storage.py`) in the next PR
 - Consider a private repo for write access; shortener JSON and settings JSONs can be public read
+
+## Challenge Mode & Remote Storage
+
+- The app must support remote storage of challenge results using Hugging Face datasets.
+- The leaderboard for a shared challenge (`game_id`) must display all user results.
+- **Sorting:** Results are sorted by highest score (descending), then by fastest time (ascending).
+- Each user result is appended to the challenge's `users` array in the remote JSON.
+- The UI must allow submitting results to an existing challenge or creating a new one.

specs/specs.md

@@ -113,3 +113,9 @@ UI/UX
 Security/Privacy
 - Only game configuration and scores are stored; no personal data is required
 - `game_id` is a short reference; full URL is stored in a repo JSON shortener index
+
+## Challenge Mode & Leaderboard
+
+- When loading a shared challenge via `game_id`, the leaderboard displays all user results for that challenge.
+- **Sorting:** The leaderboard is sorted by highest score (descending), then by fastest time (ascending).
+- Results are stored remotely in a Hugging Face dataset repo and updated via the app.

tests/test_download_game_settings.py

@@ -0,0 +1,52 @@
+# file: tests/test_download_game_settings.py
+import os
+import sys
+import pytest
+
+# Ensure the modules path is available
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+from battlewords.modules.storage import gen_full_url, _get_json_from_repo, HF_REPO_ID, SHORTENER_JSON_FILE
+
+def test_download_settings_by_short_id_handles_both(capsys):
+    # Use a fixed short id for testing
+    short_id = "hDjsB_dl1"
+
+    # Step 1: Resolve short ID to full URL
+    status, full_url = gen_full_url(
+        short_url=short_id,
+        repo_id=HF_REPO_ID,
+        json_file=SHORTENER_JSON_FILE
+    )
+
+    # Failure branch: provide a helpful message and assert expected failure shape
+    if status != "success_retrieved_full" or not full_url:
+        print(
+            f"Could not resolve short id '{short_id}'. "
+            f"Status: {status}. "
+            f"Check repo '{HF_REPO_ID}' and mapping file '{SHORTENER_JSON_FILE}'."
+        )
+        captured = capsys.readouterr()
+        assert "Could not resolve short id" in captured.out
+        # Ensure failure shape is consistent
+        assert not full_url, "full_url should be empty/None on failure"
+        return
+
+    # Success branch
+    assert status == "success_retrieved_full", f"Failed to resolve short ID: {status}"
+    assert full_url, "No full URL returned"
+
+    # Step 2: Extract file path from full URL
+    url_parts = full_url.split("/resolve/main/")
+    assert len(url_parts) == 2, f"Invalid full URL format: {full_url}"
+    file_path = url_parts[1]
+
+    # Step 3: Download and parse settings.json
+    settings = _get_json_from_repo(HF_REPO_ID, file_path, repo_type="dataset")
+    assert settings, "Failed to download or parse settings.json"
+
+    print("Downloaded settings.json:", settings)
+    # Optionally, add more assertions about the settings structure
+    assert "uid" in settings
+    assert "word_list" in settings
+    assert "score" in settings